Introduction

MADCAT logo
[image]

MADCAT User Guide
Introduction
Send Feedback
MADCAT User Guide v1.2.2

Dear user,

Welcome to the MADCAT help file. This document covers all the aspect of the MADCAT from the installation process to the most advanced tool development process.

Of course, in addition to this guide, you can contact me to ask questions, report problems... Feel free to give feedback, I'd really appreciate your support to make the MADCAT as useful as possible.

Compilation Of Windows

What is the MADCAT ?

First, the MADCAT is an acronym which stands for Multipurpose Application for Data Collection And Treatment. Key words are :

  • Multipurpose : the MADCAT can virtually perform any task
  • Data Collection : the MADCAT is based on Xml data. The core function is data storage and maintenance : create, edit, delete Xml elements.
  • Treatment: the MADCAT can execute any task using your Xml data : generate report, produce new data, interact with your system...

How does the MADCAT work ?

The MADCAT is a light framework based on Xml and .Net : Xml is used to setup the interface and define your data model. .Net is used to develop types, tools and renderers for the MADCAT.

What does the MADCAT offer by default ?

The MADCAT provides :

  • a flexible and customizable graphical interface
  • a Xml data editor
  • a task manager
  • Xsl transformation to generate HTML reports

The graphical interface is designed in order to be as simple as possible for the end-user but also for the developer. For the user, only useful elements are visible. Functions are limited but fast. For the developer, the interface can be changed very easily using Xml files.

The Xml data editor is designed like the Windows' explorer. Xml elements are displayed like files in folders. It is also very flexible for the developer because it is based on Xml files and can be modified without impact on user's data. The editor is very easy to use and is powerful : it offers infinite undo/redo, baseline management, search tool, etc...

The task manager can run multiple actions in background or not. It offers user-friendly functions like : pause/resume, full log, detailed progress report, cancel. It also offers data protection against inconsistencies. Users can cancel any actions without fear : data changes are commited to the database only if action's ended properly. Users have full control on actions.

Finally, the report generator is a simply Xsl transformation tool which can produce HTML files from the Xml data. It offers configurable Xsl transformations : users can define the scope of the report.

Can we extend the MADCAT functions ?

Yes ! The MADCAT comes with a detailed API which can be used by developers to add new data types, new renderers and new tools to the MADCAT.

Possibilities are virtually limitless. The MADCAT's design allows you any combination of types/tools/renderers/models. You can create applications by simply assembling these MADCAT elements into workspaces. The MADCAT's elements must always be designed to be reusable with any other element without installation, compilation.... Users just need to move them in dedicated folders of their workspaces.

Why the MADCAT ?

The objective is to have a very fast and light framework which is also powerful and flexible. It can be seen as a light "Eclipse" environment using .Net assemblies (for tools, types and renderers) but without the numerous options and files of the official Eclipse system.

Table of contents

This document will guide you through every step of the MADCAT experience, starting from the surface to finally reach the deepest features :

  • The installation process (easy part !)
  • The graphical interface (Easy too, it is a classical Windows interface)
  • The workspace definition process (Difficulties start here : Xml knowledge is mandatory)
  • The MADCAT's element development process (For experts : Xml and .Net are needed)
Help documentation built with Sandcastle Help File Builder

Send comments on this topic to contact@themadcat.fr

(c)2012,2013 Eric Pageron


License Agreement

[image]

MADCAT User Guide
License Agreement
Send Feedback
MADCAT User Guide v1.2.2

Microsoft Public License

This license governs use of the accompanying software. If you use the software, you accept this license. If you do not accept the license, do not use the software.

Definitions

  • The terms "reproduce," "reproduction," "derivative works," and "distribution" have the same meaning here as under U.S. copyright law.
  • A "contribution" is the original software, or any additions or changes to the software.
  • A "contributor" is any person that distributes its contribution under this license.
  • "Licensed patents" are a contributor's patent claims that read directly on its contribution.

Grant of Rights

  • (A) Copyright Grant - Subject to the terms of this license, including the license conditions and limitations in section 3, each contributor grants you a non-exclusive, worldwide, royalty-free copyright license to reproduce its contribution, prepare derivative works of its contribution, and distribute its contribution or any derivative works that you create.
  • (B) Patent Grant - Subject to the terms of this license, including the license conditions and limitations in section 3, each contributor grants you a non-exclusive, worldwide, royalty-free license under its licensed patents to make, have made, use, sell, offer for sale, import, and/or otherwise dispose of its contribution in the software or derivative works of the contribution in the software.

Conditions and Limitations

  • (A) No Trademark License - This license does not grant you rights to use any contributors' name, logo, or trademarks.
  • (B) If you bring a patent claim against any contributor over patents that you claim are infringed by the software, your patent license from such contributor to the software ends automatically.
  • (C) If you distribute any portion of the software, you must retain all copyright, patent, trademark, and attribution notices that are present in the software.
  • (D) If you distribute any portion of the software in source code form, you may do so only under this license by including a complete copy of this license with your distribution. If you distribute any portion of the software in compiled or object code form, you may only do so under a license that complies with this license.
  • (E) The software is licensed "as-is." You bear the risk of using it. The contributors give no express warranties, guarantees or conditions. You may have additional consumer rights under your local laws which this license cannot change. To the extent permitted under your local laws, the contributors exclude the implied warranties of merchantability, fitness for a particular purpose and non-infringement.

Third Parties

The MADCAT contains elements made with the following existing components :

  • Crom.Controls.Docking : Developed by Cristinel Mazarine. See the web site :

    Crom.Controls
  • Nullsoft Scriptable Install System
  • Sandcastle Help File Builder


Install instructions

[image]

MADCAT User Guide
Install instructions
Send Feedback
MADCAT User Guide v1.2.2

Installation is very easy. You start the file MADCATInstaller.exe and follow the instructions.

Prerequisite

Minimum system requirements :

  • Windows XP, Vista, 7
  • .Net Framework 4.0 or more
  • Visual C runtime librairies (vcredist). This item is included in the MADCAT installation program. It can be installed with the MADCAT if you don't have it.
  • At least than 20Mbytes for application files
  • Visual Studio Express (for element development only)

Installation process

The installation tool will install :

  • MADCAT Core (Executable, Librairies, Xml Schemas and Help files)
  • The Visual C runtime librairies (vcredist) if you don't have them on your system
  • The workspace editor (It is a MADCAT application which can be used to create workspace definitions). This is optional.
  • The workspace repository (if you want to share MADCAT elements among several workspaces and ease the management of your MADCAT elements). This is optional.
  • Wizards for Visual Studio Express (to create Tools or Renderers for MADCAT) if Visual Studio Express is installed on your system. This is optional.


User interface overview

[image]

MADCAT User Guide
User interface overview
Send Feedback
MADCAT User Guide v1.2.2

This section presents the different elements of the graphical interface of a typical MADCAT application.

The startup window

Empty Start Up Screen

The startup window is the window you'll see when starting the MADCAT without any command line parameters. This startup screen has only one function : let the user select a workspace. A workspace can be selected with 2 different methods :

  • By selecting a workspace directory (when the workspace has no workspace definition file)
  • By selecting a workspace definition file

The user can select a new workspace browsing his file system. But for a faster startup, he can click on a recently loaded workspace listed in the startup screen.

Note
When the users double-clicks on a workspace definition file in the explorer of Windows, the selected workspace is started automatically and the startup screen is not used. The MADCAT directly shows the workspace's splashscreen (if it exists) and then the main window.

Using the command line (Expert users)

the MADCAT can also be started from the command line and it supports several commands :

Command Description
-d WorkspaceFolder

Starts a workspace using a folder structure (without a XWS file)

WorkspaceFolder is a folder which contains a valid workspace structure

i.e. the selected folder shall have the following structure :

  • a sub-folder named "Models" where model files are stored
  • a sub-folder named "Tools" where tool definition files and their DLL are stored
  • a sub-folder named "Project" where the database will be stored
  • a sub-folder named "Types" where the user-defined type managers will be stored
  • any other sub-folders referenced in the definition files found in the previous folders (bitmaps for buttons, icons, ...)
-f WorkspaceDefinitionFile

Starts a workspace using a workspace definition file

WorkspaceDefinitionFile is a valid workspace definition file

-r WorkspaceDefinitionFile ActionName Selection [Parameter1 [Parameter2] ...]

Performs an action on a given selection of a given workspace. All the messages are directly displayed on the console output.

  • WorkspaceDefinitionFile is a valid workspace definition file
  • ActionName is the name of the action to perform. Must be the name of an action exposed by one of the tools of the workspace
  • Selection is a XPath expression which defines the selection on which the action shall be performed
  • ParameterN is a serie of values which are passed to the tool for the execution of the action. It is optional.


the Workspace area

[image]

MADCAT User Guide
the Workspace area
Send Feedback
MADCAT User Guide v1.2.2

This topic contains the following sections.

  • The main window
  • The main bar
  • The main menu
  • The data sources' bar
  • The tools' bar

The main window

Main Workspace Form

The main window is the window opened when a workspace starts. It is the graphical representation of a MADCAT workspace. It has a menu bar to access main functions of the MADCAT, a database bar to access the workspace's data and one or more tool bars depending on the loaded tools. To learn more about workspaces, read the section Workspace Description

The main window is also the parent window of all the database explorer windows the user will open. This is the actual work space.

All this graphical controls are presented below.

Top Main Workspace Form

The main bar

Madcat Tool Bar

The main bar has buttons to activate main functions of MADCAT which are :

  • Open a workspace
  • Switch to a recently loaded workspace
  • Save changes in database
  • Open the configuration panel
  • Find items
  • Undo/Redo
  • Open the reports panel
  • Open the logbooks
  • Open the task manager

The main menu

Menu Main Expanded

The data sources' bar

Data Source Button Process

This bar contains one button per data source loaded during the workspace startup sequence. When the MADCAT finds data file matching a valid model (i.e. compliant with models' schema and loaded in the workspace), a button is created in this bar. To learn more about models, check the section Models. Clicking on the button will open a new explorer window which can be used to navigate into the database, create, edit or delete items, ...

Moving your mouse cursor over a button will display the full path of the data file of the data source

The tools' bar

Depending on the group of actions found in the tool definition files of the loaded workspace, the MADCAT will generate one or more tool bars. A tool bar will be created for each group found in the tool definition file. For more information about tool definition files, read the section Tool Definition File.

Each tool bar will contain one button for each action of the corresponding group. Clicking on the button will activate the related action. Buttons are enabled depending on the selection performed by the user in the explorer windows.

Tool Action Button Process

Tool bars are displayed/hidden with a specific context menu.

Tool Bar Context Menu

Their size and appearence is also controlled by another context menu.

Strip Bar Context Menu


the Explorer Windows

[image]

MADCAT User Guide
the Explorer Windows
Send Feedback
MADCAT User Guide v1.2.2

The explorer window is the main window for data management. It provides access to data and has all the functions the users need to navigate, find, create, edit, delete items, folders and links in the database. An explorer window is attached to only one model. It is the graphical interface for the data defined by a model of the workspace. To learn more about models, check the section Models.

Explorer windows are composed of several tool bars, a tree view and a renderer panel. The renderer panel is the place where the renderers display the content of the database.

This topic contains the following sections.

  • The main action bar
  • The renderer bar
  • The tree view
  • The renderer panel
  • The multiview mode

The main action bar

Explorer Tool Bar

This tool bar contains the common buttons (in order of appearance in the screenshot above):

  • Go to the parent folder
  • Create a folder. See the section Folders for more information.
  • Edit the selected item
  • Delete the selected item(s)
  • Print the selected item(s)
  • Follow a link
  • Find links pointing to a selected item
  • Cut/Copy/Paste
  • Find an item
  • Show/Hide the tree view
  • Create items : in this case, MADCAT creates one button per item definition found in the model
  • Create series : in this case, MADCAT creates one button per series definition found in the model
  • Create links : in this case, MADCAT creates one button per link definition found in the model
Note
The buttons for creation (items, series or links) are dependent of the reference of the display (named the root item of the view). When the user moves in the database (go to upward folders, or move into item/folder), the list of buttons is refreshed.
Note
All the functions of the tool bars are also available in a context menu which is called by clicking on an item with the right button of the mouse.

The renderer bar

Explorer Renderer Bar

This bar contains one button per renderer loaded with the workspace. If the renderer support several display modes, the button shows a dropdown list when clicked; each dropdown item is a mode of the renderer. For more information about renderers, read the section Renderers. Click on a button or a dropdown item to instantly change the display mode.

Note
The renderers can add new controls in this bar. This is totally dependent of the active render. For example, the list view renderer adds 2 buttons : one which shows/hides the inline edit form and one which actives/deactivates the filters.

The tree view

The tree view is comparable to the tree view of the explorer of Windows : it is used to navigate quickly from one point to another in the database. It contains all the database elements which can have children elements : this can be items, queries or folders (model folders or user folders). Just click on a leaf of the tree to move and refresh the display.

The tree can be displayed in 2 different ways :

Classical tree view (standard MS Windows control) | Sliding slices view (like iPod menus)
Full Explorer Tree Config | Explorer Tree Slices

The user can define what is displayed in the tree view. The node elements can be :

  • Any item having children

  • Any item having children except series

  • Any item

Example

Any item having children except series | Any item
Default Explorer Tree Config | Full Explorer Tree Config

This definition is done separately for each explorer through the configuration panel.

Default Model Properties
Note
The tree changes the current selection. When you click on a leaf, the leaf is the new selection. This new selection will be used for next cut/copy/paste/delete/print/tools operations.

The renderer panel

Explorer Renderer Area

This panel is the area where renderers can freely add their controls. This part is totally under their control. All the users' actions performed in this area are managed by the active renderer.

The multiview mode

With the new version 1.2 of the MADCAT, explorer windows can display more than one renderer at a time. This feature is called the multiview.

In standard mode, an explorer window can activate only one renderer at a time. Of course you can open several explorers for the same data source but they will never be synchronized ; i.e. if you navigate in one explorer, the others don't move to the current item automatically.

In the multiview mode, your explorer can activate several renderers in a synchronized navigation system. Navigation performed in one renderer has a direct effect on the others.

It is activated through the configuration panel model per model. Each explorer of a workspace can be displayed in "Multiview" mode or not. It is controlled through the configuration panel of the MADCAT by double-clicking the model icon and then activate the option "Use Multiview".

Default Model Properties
Note
This feature has been implemented using the excellent control Crom.Controls.Docking developed by Cristinel Mazarine.

When this mode is activated, when the user clicks on a renderer button (or selects a mode in a dropdown menu of a renderer button), a docakble form is generated inside the renderer area of the explorer window.

Explorer Multiview Area

The renderer area is then composed of one or more dockable forms. In this mode, users can setup their windows as they want and enhance the visibility of the data. A dockable form can be docked on any edge of the renderer area :

Top | Bottom | Left | Right
Explorer Multiview Top | Explorer Multiview Bottom | Explorer Multiview Left | Explorer Multiview Right
Note
All the forms docked to one of these edges can be hidden in the border to gain some space in the renderer area. When a form is hidden, a tab with the form name is displayed on the edge of the renderer area and a snapshot of the hidden form is shown every time the mouse cursor moves over the tab :
Explorer Multiview Hidden Form

Forms can also fill the entire explorer window or the remaining space (fill) :

Explorer Multiview Fill

When multiple forms occupy the same area, tabs are added to switch from one form to another :

Explorer Multiview Fill Tabs

The user can open as many renderers as he needs and dock their respective forms anywhere by performing drag'n'drop operation with their title bars. When drag'n'drop starts, helpers are displayed in blue to dock the form easily :

Explorer Multiview DragNDrop
Note
The layout is automatically saved when the explorer window is closed and applied each time the explorer window is opened in multiview mode.

Finally, the multiview can be controled through the model. You can define a particular configuration for a type of item, folder or series. See the section Multiview for more information.


the Configuration Panel

[image]

MADCAT User Guide
the Configuration Panel
Send Feedback
MADCAT User Guide v1.2.2

The configuration panel is the main user interface for workspace configuration. The user can configure any element inside the current workspace : Models, Tools and Renderers.

This topic contains the following sections.

  • Overview
  • Properties for models
  • Properties for tools
  • Properties for renderers

Overview

The configuration panel is a window with 3 parts :

  • Models part : There is one icon per model.

  • Tools part : There is one icon per tool.

  • Renderers part : There is one icon per renderer.

Properties for models

For models, 3 parameters are always available :

  • Content of the navigation tree

  • Activation of the multiview mode

  • The type of navigation tree : Classic or sliding slices

Default Model Properties

When a model has trigger definitions, additional settings are added for triggers so users can active/deactivate the existing triggers of each model.

Default Model Properties With Triggers

Properties for tools

For Tools, available settings are dependent of the tool : Each tool defines its own set of configuration parameters. This is done by the tool's developer using MADCAT's API. This cannot be controlled by the tool definition files.

Properties for renderers

For Renderers, available settings are dependent of the renderer : Each renderer defines its own set of configuration parameters. This is done by the renderer's developer using MADCAT's API. This cannot be controlled by the renderer definition files.


Running Actions

[image]

MADCAT User Guide
Running Actions
Send Feedback
MADCAT User Guide v1.2.2

The principle

Your workspace can have tools which can perform actions. Actions are defined in the tool definition files. They are linked to items of Model inside the models (see action associations).

The task manager window

This window lists all the actions performed, canceled running or ready for execution. It also provides access to the following functions :

  • Control actions (pause,resume,cancel,restart) via the progress display form
  • View progress status of running actions
  • View execution log


Control actions

[image]

MADCAT User Guide
Control actions
Send Feedback
MADCAT User Guide v1.2.2

Controls

Depending on actions' parameters defined by the tool definition file, the end-user can pause, resume or cancel a running action from the process manager window or from the progress window of the action.

Action Progress Window Controls

The window gives the overall progress (all steps of the action included)

Action Progress Window Simple

The progress window can also display the status of each step of the running actions. Steps are defined by the tool itself using the MADCAT's API. This feature may not be available with all tools.

Action Progress Window Extended

When the action is over, the steps list gives the total execution time of each step.


Execution Progress

[image]

MADCAT User Guide
Execution Progress
Send Feedback
MADCAT User Guide v1.2.2

Many elements in the interface can gives you an overall status of the running actions. These elements are described in this section.

Overall progress monitoring

Each action has its own progress window which can be displayed or hidden at any time. the MADCAT also indicates the number of running processes and the overall progress in the title bar and status bar of the main window.

Action Progress Monitoring

Logbooks also provides an access to the status of the running actions as you can see in real-time all the messages produced by them.

Action Progress With Logbooks
Note
Note that the colors of the lines of the logbook can be controlled by the tool using the API of MADCAT


Execution Log

[image]

MADCAT User Guide
Execution Log
Send Feedback
MADCAT User Guide v1.2.2

The MADCAT records several information about each action :

  • Start time, end time and duration
  • The context of execution of the action (XML elements of the project data, input parameters)
  • Data transactions performed by the action
  • Messages produced by the action

Execution Log (Inputs)

All the input data can be analysed in the execution log window :

  • The Xml data sent to the tool for the action (with all children and all the attributes)

  • The parameters defined by the user using the Action Wizard (this is dependent of the tool. Action Wizard is invoked with the MADCAT API)

Note
Parameters which are defined using Query dialog boxes (with the method Query of the MADCAT API for Logbook writers) can be seen among the messages produced by the tool on the output side of the execution log.
Action Execution Report Input

This window can be displayed from the progress window of any action listed in the process manager.

Execution Log (Outputs)

All the messages can be analysed in the execution log window.

The window contains also all the data transactions performed by the tool and commited to your project.

Action Execution Report Output

This window can be displayed from the progress window of any action listed in the process manager.

Note
Please note that execution log can't be saved into a file. The log is lost when the MADCAT is shutdown. Only messages can be saved into a XML file. See logbooks section.


the Reports Panel

[image]

MADCAT User Guide
the Reports Panel
Send Feedback
MADCAT User Guide v1.2.2

The report panel

The report panel contains all the report defined in the current workspace. Reports are generated by double-clicking on a report in this panel. To get more informations about reports, read this page Reports.


the Logbooks
Send Feedback
MADCAT User Guide v1.2.2

This topic contains the following sections.

  • The logbooks
  • The messages
  • Creating logbooks
  • Saving logbooks to disk
  • Deleting logbooks
  • Reseting logbooks

The logbooks

A logbook is a view to the history of the messages produced by the tools/renderers of MADCAT (and MADCAT itself too). A workspace can have one or several logbooks. All the logbooks are displayed in the logbook browser (one tab per logbook) :

Note
Note that the background color and foreground color of the lines of the logbook can be controlled by the tool using the API of MADCAT for each message.

The messages

A message is like this in its simple form :

Logbook Warning Message

Depending on the creator of the message, additional information can be available such as :

  • Help. Additional data which helps you understanding the message.

  • Console. Raw console output if the message is linked to the execution of an external program launched from the OS console.

  • Item. Xpath of the element which is in relation with the message.

A message can be displayed when it is generated to get user's acknowledgment or it can be hidden. In this case, the only way to see the message is to have a logbook configured to capture the message. When a message has not been acknowledged by the user, the MADCAT shows the following notification in the message window :

Logbook Message Not Shown Notification
Note
In any cases, all the messages are stored in the MADCAT's memory. They are kept until the user quits the MADCAT. Even if you switch from one workspace to another, messages are kept in memory.

Creating logbooks

Because workspaces may generate a lot of messages, users must define some capture criterias for their logbooks. These criterias are :

  • Message category : Information, Warning, Error, Confirmation, Question. A logbook can capture all categories or only some of them.
  • Producer : the MADCAT element which has generated the message. A logbook can capture all the messages or only the messages produced by one tool or renderer or model of the workspace.
  • Related action : the tool's action which has generated the message. For tools' messages, the user can also select only the messages coming from one specific action.

It is important to note that logbooks are attached to workspaces. When a workspace is loaded, the logbooks created in it are automatically activated with their filters and features.

Note
Because all messages are stored in memory, users can create a logbook after several messages being generated and still be able to see them. Just initialize the logbook with all the previously generated messages matching the logbook's settings.

Saving logbooks to disk

Via the browser, the content of a logbook can be instantly saved to disk. Click on the "Save" button of the logbook browser and select an output file.

Messages are saved in XML format like this :

CopyXML
<LOGBOOK NAME='all'>
<DESCRIPTION>This logbook shows the following message(s) :
- Errors
- Informations
- Warning
- Confirmations
- Questions
logged by any process when performing any action.</DESCRIPTION>
<MESSAGE DATE="09/12/2012 15:12:09" LEVEL="WAR" LOGGEDBY="MADCAT" ACTION="" ITEM="" ANSWER="" DISPLAYED="NO"><DESCRIPTION>D:\Workspaces\global.xws : No path for types defined in workspace definition file. Using default types path.</DESCRIPTION><HELP></HELP><CONSOLE></CONSOLE></MESSAGE>
<MESSAGE DATE="09/12/2012 15:12:09" LEVEL="WAR" LOGGEDBY="MADCAT" ACTION="" ITEM="" ANSWER="" DISPLAYED="NO"><DESCRIPTION>D:\Workspaces\global.xws : No path for reports defined in workspace definition file. Using default reports path.</DESCRIPTION><HELP></HELP><CONSOLE></CONSOLE></MESSAGE>
<MESSAGE DATE="09/12/2012 15:12:09" LEVEL="INF" LOGGEDBY="MADCAT" ACTION="" ITEM="" ANSWER="" DISPLAYED="NO"><DESCRIPTION>Loading user profile...</DESCRIPTION><HELP></HELP><CONSOLE></CONSOLE></MESSAGE>
<MESSAGE DATE="09/12/2012 15:12:09" LEVEL="INF" LOGGEDBY="MADCAT" ACTION="" ITEM="" ANSWER="" DISPLAYED="NO"><DESCRIPTION>User profile loaded</DESCRIPTION><HELP></HELP><CONSOLE></CONSOLE></MESSAGE>
<MESSAGE DATE="09/12/2012 15:12:09" LEVEL="INF" LOGGEDBY="MADCAT" ACTION="" ITEM="" ANSWER="" DISPLAYED="NO"><DESCRIPTION>Loading data from D:\Workspaces\ProjectGlobal\3.1</DESCRIPTION><HELP></HELP><CONSOLE></CONSOLE></MESSAGE>
<MESSAGE DATE="09/12/2012 15:12:10" LEVEL="ERR" LOGGEDBY="MADCAT" ACTION="" ITEM="" ANSWER="" DISPLAYED="NO"><DESCRIPTION>Can't load data from D:\Workspaces\ProjectGlobal\3.1\TESTDB.XML. Model TEST is missing.</DESCRIPTION><HELP></HELP><CONSOLE></CONSOLE></MESSAGE>
</LOGBOOK>

Another way is to configure a logbook to automatically store its content in the user's filesystem on the fly. By default, they are not stored and messages are lost when the user quits MADCAT. So activate the "Save to disk" feature and give an output file to automatically save all the messages to disk in live. This is very useful when you use an action which kills the MADCAT (due to a fatal exception in a tool for example). You'll see the last generated messages (just before the end of execution of the MADCAT). This may help you understand why the action generates a fatal exception.

Logbook Save To Disk

Deleting logbooks

If you don't want a logbook anymore you have to delete it by using the "Delete" button of the logbooks browser.

Reseting logbooks

If you want to clear the content of a logbook, just reset it. Messages are not actually deleted. They are justed removed from the logbook. They may be seen in another logbook or retrieved again by initializing the logbook with all the previously generated messages matching the logbook's settings.


Data management

[image]

MADCAT User Guide
Data management
Send Feedback
MADCAT User Guide v1.2.2

This chapter describes how data is managed with the MADCAT. You'll learn how data is loaded, modified and baselined.


How data is authored

[image]

MADCAT User Guide
How data is authored
Send Feedback
MADCAT User Guide v1.2.2

Your data is the most important thing in the MADCAT. So many features have been implemented to preserve it as far as possible. This section describes the method which are available during one session of work with the MADCAT.

Edit data manually

This is the most common way. The user edits his data manually by using the standard forms or renderers' interfaces

In this mode, an undo/redo feature preserves your data from unwanted modifications.

The undo/redo feature records all the actions performed by the user during the active session of the workspace. The history is not persistent: it is lost once the application is closed or the workspace is closed (workspace switching).

Edit data with tools

Tools can access data. Because tools may impact a lot of data very quickly, the MADCAT provides enhanced mechanism to preserve it from unwanted changes.

The first one is the undo/redo feature which works with tools' actions. If after the end of the execution of an action you detect data corruption (due to a bug in a tool for example), you can simply undo the action in one click.

Undo Redo Buttons

Another method is to lock the access to data editing for a specific action of a tool by setting the option "readonly" of this action to "yes". In this mode, the action will change the data but the changes won't be commited to the actual project's data. To achieve this protection, the MADCAT always execute tools with a copy of your data. All changes performed by the tool on this copy is recorded by the MADCAT. If everything is fine (i.e. the execution of the action is successfull), the MADCAT will perform exactly the same changes to the actual data.

So if an action with readonly set to off doesn't end properly, the MADCAT can discard the changes performed on the data. A confirmation from the user will be required to accept the changes.

The last feature of the MADCAT is the ability to list all the changes commited to the actual data at the end of each run of an action. The detailed log shows you the following :

  • The data used as input (selected items when the action started)

  • The parameters entered by the user during the initialization phase of the execution of the action

  • The messages produced by the tool during the execution

  • The list of changes performed on the data

How data is stored

the MADCAT saves your data into XML files. These files are stored in the project data path set by the workspace definition file or in the folder "Project" if no Workspace definition files exist.

A XML file is automatically initialized when the user creates his first item with a model. Each model will have its own XML file. The XML file refers to its model so the MADCAT is always able to find the definitions corresponding to the data.

ITEM, SERIES, LINK and FOLDER are elements which will control the generation of XML elements in the database. Xml element defined by ITEM, SERIES and LINK elements are created on users' control. MADCAT offers specific buttons to create, edit and delete Xml elements made from ITEM, SERIES and LINK elements. FOLDER are under MADCAT control only. FOLDER elements which are on the top of the model hierarchy automatically generate Xml elements in the database when it is loaded. FOLDER elements which are under an ITEM or a FOLDER element will automatically generate a XML element below the XML element created for the ITEM or LINK. The hierarchy of these XML elements of models directly defines the hierarchy of the XML elements in the user's database.

Note
Xml elements are ordered in their order of creation by the user. Models don't control the order of Xml elements in the database.

the MADCAT automatically adds some attributes to these elements. Because these attributes are used by the MADCAT, their names are reserved and shall never be used in your models :

  • ID : This attribute contains the unique ID of the data element in your database. It is composed of a number followed by the database name like this : 999,NAME
  • TYPE : This attribute contains the type of database element for the MADCAT. It used to detect the MADCAT links.

If you change the value of there attributes manually or with a XML editor, the MADCAT may not be able to handle the data properly. Do it at your own risk ! The root XML element of the database file is also defined by the model. This element shall never be modified manually. The attributes of this element are managed by the MADCAT only (reserved).

How data is synchronized with models changes

If the definition changes after the data is being created, the data will be synchronized with the new version of the definition the next time the user will edit an item. Only the data of the edited item is synchronized.

For example : If you have the following definition :

CopyXML
<ITEM NAME="BaseRequirement" NODENAME="REQBASE" ICON="" STYLESHEET="" RENDERER="" RENDERMODE="" RENDEROPTIONS="">
  <ATTRIBUTE NAME="TITLE" DESC="Title" HELP="" TYPE="STR" OPTIONS="mandatory=yes" />
  <ATTRIBUTE NAME="TEXT" DESC="Text" HELP="" TYPE="TXT" OPTIONS="mandatory=yes,lines=5" />
  <ATTRIBUTE NAME="VERS" DESC="Version" HELP="" TYPE="NUM" OPTIONS="mandatory=yes,mini=1,maxi=99" />
  <ATTRIBUTE NAME="STATUS" DESC="Status" HELP="" TYPE="ENUM" OPTIONS="mandatory=yes">
    <ENUM VALUE="draft" />
    <ENUM VALUE="in review" />
    <ENUM VALUE="validated" />
    <ENUM VALUE="obsolete" />
  </ATTRIBUTE>
</ITEM>

  <ITEM NAME="Technical Requirement" NODENAME="TECHREQ" ICON="" STYLESHEET="" RENDERER="" RENDERMODE="" RENDEROPTIONS="">
    <ATTRIBUTE NAME="RATIONALE" DESC="Rationale" HELP="" TYPE="TXT" OPTIONS="lines=5" />
    <ATTRIBUTE NAME="UPREQ" DESC="Upward Requirements" HELP="" TYPE="ItemTypeHandler" OPTIONS="" />
    <INHERITS NODENAME="REQBASE" DATAMODEL="SYSREQ" OVERRIDE="YES" />
  </ITEM>

The created items may be the following :

CopyXML
<TECHREQ TITLE="Safety test 1" VER="" TEXT="Blabla for requirement 1" RATIONALE="" UPREQ="" ID="3,DemoWrkspc/SYSREQ" TYPE="" VERS="" STATUS="" />
<TECHREQ TITLE="Safety test 2" VER="" TEXT="Blabla for requirement 2" RATIONALE="" UPREQ="" ID="4,DemoWrkspc/SYSREQ" TYPE="" VERS="" STATUS="" />

Now the definition is changed into this (added attribute 'EXTRAATTRIBUTE').

CopyXML
<ITEM NAME="Technical Requirement" NODENAME="TECHREQ" ICON="" STYLESHEET="" RENDERER="" RENDERMODE="" RENDEROPTIONS="">
  <ATTRIBUTE NAME="RATIONALE" DESC="Rationale" HELP="" TYPE="TXT" OPTIONS="lines=5" />
  <ATTRIBUTE NAME="UPREQ" DESC="Upward Requirements" HELP="" TYPE="ItemTypeHandler" OPTIONS="" />
  <ATTRIBUTE NAME="EXTRAATTRIBUTE" DESC="Additional Attribute" HELP="" TYPE="STR" OPTIONS="" />
  <INHERITS NODENAME="REQBASE" DATAMODEL="SYSREQ" OVERRIDE="YES" />
</ITEM>

The 1st item is edited. The 2nd is left unchanged by the user. The XML file will be changed like this :

CopyXML
<TECHREQ TITLE="Safety test 1" VER="" TEXT="Blabla for requirement 1" RATIONALE="" UPREQ="" ID="3,DemoWrkspc/SYSREQ" TYPE="" VERS="" STATUS="" EXTRAATTRIBUTE=""/>
<TECHREQ TITLE="Safety test 2" VER="" TEXT="Blabla for requirement 2" RATIONALE="" UPREQ="" ID="4,DemoWrkspc/SYSREQ" TYPE="" VERS="" STATUS="" />


Import and Export

[image]

MADCAT User Guide
Import and Export
Send Feedback
MADCAT User Guide v1.2.2

New with the version 1.2, the MADCAT can now import and export data from your database to a standalone XML file.

Import Data

  1. To import data, select the location where external data should be imported using an explorer window and clicking on an item or a folder. The selected element will be the parent of the imported elements.

  2. Then select the command "Import" in the menu "File".

  3. Select the XML file where the data is and confirm the selection : the import process starts.

  4. The import process is managed like any tool's action in the task manager. So you can easily monitor the process.

Export Data

  1. To export data, select the data that should be exported using an explorer window and clicking on an item or a folder. The selected element and all its children elements will be exported. The links are resolved (see the section Link for more information about links).

  2. Then select the command "Export" in the menu "File".

  3. Select the XML file where the data will be written to and confirm the selection : the export process starts.

  4. The export process is managed like any tool's action in the task manager. So you can easily monitor the process.

Note
When the MADCAT exports data, reserved attributes ID and TYPE are removed from the XML elements. The XML file is 'clean' as it contain only your data and not the MADCAT's management data.


Baseline Mechanism

[image]

MADCAT User Guide
Baseline Mechanism
Send Feedback
MADCAT User Guide v1.2.2

Baseline is the ultimate mechanism to control the changes performed on the data. It records all the changes performed at any moment and the history is kept undefinitely.

Definition

A baseline can be considered as a version of your project fixed at a given moment. Each baseline is given a name which identifies this version and helps you understand what it is for.

A baseline has 2 states : Open or Closed.

When it is open, the data can be changed. All changes are recorded.

When it is closed, the data can't be changed for this baseline. A new one must be opened to continue editing the data.

Activate baseline management

This is done with the workspace definition file by adding a BASELINE Xml element :

Switching of baselines

When baselines are closed, the data they contain can be viewed at any time. You can easily see how was your project when the baseline was closed. the MADCAT can open any baseline at any time. You can safely switch from your current working baseline to any other baseline by using the menu "Baseline > Select baselines..."

Creation of baselines

Two different ways exist. The prefered one is the following :

You can start a new baseline from any closed baseline. First, switch to a closed baseline with the command "Baseline > Select baselines..." then select the command "Start a new baseline from ..."

Baseline New From ClosedBL

Then enter a baseline name.

Note
New with the version 1.2 of the MADCAT : Baseline name can be changed at any time.

The new baseline will be created where the data of the selected closed baseline can be changed again. The new baseline is considered as a child baseline of the closed one.

This system can be performed several times and from any closed baseline.

So you can compose complex baselines tree with several opened baselines in parallele.

Baseline Tree For Data Source

Analysis of baselines

As all the changes performed within a baseline are recorded, the MADCAT can show you all the changes performed on the data from any baseline to any ancestor of this baseline (called the reference baseline).

Changes are shown directly with colors on items. 3 colors are used to detect changes easily :

  • Green : Item has never been changed since the reference baseline

  • Yellow : Item has changed since the reference baseline. All changes are saved to the XML file of the project.

  • Red : Item has changed since the reference baseline. At least one change is not saved to the XML file of the project.

All 'red' items will turn into 'yellow' when you save your project.

When an item is in 'yellow' or 'red', you can see all the changes performed on the item since the reference baseline by clicking on this button :

The reference baseline can be changed very quickly by selecting it in the menu "Baseline". This menu lists all the ancestors of the current baseline (the one set by your workspace definition file or the command "Select baselines..." of the menu "Baselines").

Files of baselines

The data of each baseline is stored in a sub-folder of the project data path of the workspace. The name of the sub-folder is the name of the baseline.

The data it contains is managed like a classic project folder : it is a set of XML files (see How data is authored for more details).

In addition, a specific XML file is managed by the MADCAT : the baseline file (XBL). This file is located in the project folder of your workspace at the same level as the sub-folder. The file name is the baseline name.

This file contains all the changes performed on the data for the baseline. It also contains the state of the baseline and the configuration of the external data sources if the baseline is closed (see Data sharing for more details).


Share data between workspaces

[image]

MADCAT User Guide
Share data between workspaces
Send Feedback
MADCAT User Guide v1.2.2

This chapter is related to data sharing among several workspaces. This is usefull when the data is managed by several persons (a team) within a process : someone is creating the data used by someone else, for example.

Data Sharing

One powerful feature is the data sharing mechanism of MADCAT.

Each workspace has its own project data but it can also access other workspaces' data.

User can control easily the source of data for his project : you can add or remove sources at any time.

Note that the baseline mechanism works when sharing data. So you can select one specific baseline among others as a source of data for your workspace.

For example, when you work on a project with other teams, each team having its workspace, it is recommended to use the baselines. One team can baseline its data before sharing it with other teams. Doing this, will allow this team to continue working on its data without impacting the other teams. Each time a new baseline is closed by the leader team, teams can update their sources of data to take the latest baseline.

Configure Data Sharing

It is very easy to setup. You have also 2 ways to do this :

  • By editing the workspace definition file

  • By using the MADCAT user interface in your application

Edit the workspace definition file

If you want to edit the workspace definition file, use the tag PROJECTPATH to add a data source. The PROJECTPATH tag must contain the location of the data (path only). The MADCAT will load automatically the data files located in the given path if the corresponding model file is also loaded in your workspace.

Use the graphical interface

If you want to add or remove a data source, right-click on the data sources bar of the application and select "Add a data source".

Data Sources Context Menu

To add a source, select a path.

Data Sources Add

If baselines exist in the selected path, an additional dialog box will open to ask you to select the baseline you want to open.

Baseline Tree For Data Source

To remove a source, right-click on the data sources bar of the application and select "Remove data source(s)".

select one or several source(s) in the dialog box then click OK.

Data Sources Remove

Using Baselines

You can refer to baselines created in other workspaces with the tag PROJECTPATH.

By setting its attribute "BASELINE" to the name of the baseline you want to see, the data located in location specified by the PROJECTPATH tag will be the one coming from this baseline.

CopyXML
<?xml version="1.0" encoding="UTF-8"?>
<WORKSPACE xmlns="http://www.themadcat.fr/workspaces" NAME="TriggerTest">
  <IDENTIFIER>TRIGTESTWRKSPC</IDENTIFIER>
  <DESCRIPTION>Workspace used to test triggers</DESCRIPTION>
  <AUTHOR>E.Pageron</AUTHOR>
  <BASELINE>1.2</BASELINE>
  <PROJECTPATH>Project</PROJECTPATH>
<legacyBold xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5">  <PROJECTPATH BASELINE="1.3b">D:\Workspaces\Composite\Reqm\Project</PROJECTPATH>
</legacyBold>  <MODELSSELECTION PATH="Models" WORKSPACEPATH="" RULE="AddAllThenIgnore" />
  <TOOLSSELECTION PATH="Tools" WORKSPACEPATH="" RULE="AddAllThenIgnore" />
  <RENDERERSSELECTION PATH="Renderers" WORKSPACEPATH="" RULE="AddAllThenIgnore" />
</WORKSPACE>

In this case, the data is opened in read-only mode. You won't be able to edit it.

The baselines can be changed at any time in the application by using the menu "Baselines > Select baselines..."

This will change the definition file in order to load the selected configuration each time the workspace is started.

Note
If you access baselines of other workspaces with the PROJECTPATH tag while the baseline mechanism is activated for your own workspace, the baseline configuration will be saved in the baseline file each time you close one.
Baseline Check Before Closure

Check the section Baseline Mechanism for more information.


Workspace description

[image]

MADCAT User Guide
Workspace description
Send Feedback
MADCAT User Guide v1.2.2

MADCAT runs workspaces. A workspace is a set of 4 major types of elements : Models, Types, Renderers and Tools.

In addition the workspace contains secondary elements like : folders for data storage, bitmaps, stylesheets, etc...

A workspace is an environment setup for one or several group of data on which you may execute some tasks. Depending on the data, you will select the tools and renderers you want to use to optimize your production and the management of it.

Because the life cycle of your data may be very long, you'll be able to adapt your workspace to the evolutions of your needs without impact on your data. All in MADCAT is made to be very flexible and safe for your data. So you can add or remove tools, renderers as you want. You can change your data models to add new (or remove) attributes to your data elements and so on...

This topic contains the following sections.

  • The Workspace Definition File
  • Directory structure
  • Definition File Location
  • Folders Locations
  • Activate Baseline Mechanism
  • Use the splash screen
  • Background image
  • Help File
  • Application Information

The Workspace Definition File

Workspaces are defined by XML files with extension XWS. Files are called "workspace definition files".

MADCAT can be associated to XWS files to run directly workspaces from the Windows explorer. Otherwise a startup menu let you choose the workspace to run.

A XWS file defines :

  • the workspace name,
  • the location of the models,
  • the location of the user-defined types,
  • the location of the renderers definitions (XRD files),
  • the location of the tools definitions (XTL files),
  • the location of the data storage (Project folder),
  • the current baseline,
  • the splashscreen settings,
  • the background settings,
  • the help file location,
  • and the icon of the application

Here is an example of a complex workspace definition file :

CopyXML
<?xml version="1.0" encoding="UTF-8"?>
<WORKSPACE xmlns="http://www.themadcat.fr/workspaces" NAME="TriggerTest">
  <IDENTIFIER>TRIGTESTWRKSPC</IDENTIFIER>
  <DESCRIPTION>Workspace used to test triggers</DESCRIPTION>
  <AUTHOR>E.Pageron</AUTHOR>
  <BASELINE>1.2</BASELINE>
  <PROJECTPATH>Project</PROJECTPATH>
  <PROJECTPATH BASELINE="1.3b">D:\Workspaces\Composite\Reqm\Project</PROJECTPATH>
  <MODELSSELECTION PATH="Models" WORKSPACEPATH="" RULE="AddAllThenIgnore" />
  <MODELSSELECTION PATH="Models" WORKSPACEPATH="D:\Workspaces\Repository\Educational\" RULE="AddAllThenIgnore" />
  <MODELSSELECTION PATH="Models" WORKSPACEPATH="D:\Workspaces\Repository\Test\" RULE="AddAllThenIgnore" />
  <TOOLSSELECTION PATH="Tools" WORKSPACEPATH="" RULE="AddAllThenIgnore" />
  <RENDERERSSELECTION PATH="Renderers" WORKSPACEPATH="" RULE="AddAllThenIgnore" />
  <RENDERERSSELECTION PATH="Renderers" WORKSPACEPATH="D:\Workspaces\Repository\SwDev\" RULE="AddAllThenIgnore" />
  <TYPESPATH>D:\Workspaces\Repository\SwDev\Types</TYPESPATH>
  <TYPESPATH>D:\Workspaces\Repository\Test\Types</TYPESPATH>
</WORKSPACE>

Directory structure

Physically, a workspace is a group of folders having specific objectives. These folders are :

  • Folder for models files. By default this folder is expected to be named "Models". It shall contain the XML files which define your database.
  • Folder for project's database. By default, it is expected to be named "Project". It will contain the XML data produced by the user. If baselines are active, it will contain all baselines' data.
  • Folder for tools. By default, it is expected to be named "Tools". It shall contain DLL of tools with their respective Tool Definition File (XTL).
  • Folder for renderers. By default, it is expected to be named "Renderers". It shall contain DLL of renderers with their respective Renderer Definition File (XRD).
  • Folder for types. By default, it is expected to be named "Types". It shall contain DLL of types handlers.
  • Folder for reports. By default, it is expected to be named "Reports". It shall contain Report Definition Files (XPT).

Only "Models", "Project" and "Tools" are mandatory. The names are never mandatory : you can specify the names you want. They can even be located at different places in your system (this can be very useful when you'll want to share tools, models,... between different workspaces)

In addition to these folders, it is recommended to have these ones :

  • A folder for bitmaps file. You will certainly have to use plenty of bitmap files (icons, pictures, ...) to build a nice application. Put them in one folder within the workspace directory. You'll be able to refer to them from any MADCAT's files using relative paths.
  • A folder named "Output" for reports' output file. Most of the time, your HTML files produced by the reports will need javascript files (JS), style sheet files (CSS)... If you place them in this folder, your reports will be correctly rendered in the MADCAT's report preview.

Here is an example of a typical workspace structure :

workspace folders ex

Definition File Location

The workspace definition file (XWS) shall be located in the root directory of your workspace. It is recommended leaving it alone there. User will activate the workspace by simply double-clicking this file from Window's explorer.

Folders Locations

If you don't want to use the default workspace structure described above, you can specify the exact location of each folders using specific tags. The tags are :

  • (deprecated. Use MODELSSELECTION) MODELSPATH : Location of models files
  • (deprecated. Use RENDERERSSELECTION) RENDERERSPATH : Location of the renderers
  • (deprecated. Use TOOLSSELECTION) TOOLSPATH : Location of the tools
  • PROJECTPATH : Location of the project database
  • REPORTSPATH : Location of the report definition files
  • TYPESPATH : Location of the types handlers
  • MODELSSELECTION : Location of the models handlers and selection rule applied to this location
  • TOOLSSELECTION : Location of the tools handlers and selection rule applied to this location
  • RENDERERSSELECTION : Location of the renderers handlers and selection rule applied to this location

For a more detailed description of the usage of the tag PROJECTPATH, see data sharing description.

Note
All these tags are optional. Path may be relative to the workspace location. You can use the same tags several times if your elements are located in different places of your system.

Selection rules

With the version 1.2 of MADCAT comes selection rules for MADCAT elements like models, tools and renderers.

This feature helps you select in detail what element to use in a workspace.

You have 2 rules :

  • Add then ignore : All the elements found in the location are used by default. You have to ignore them explicitly if you don't want to use them.

    Use the tag IGNORE with the filename (without the path) of the element inside.

  • Ignore then add : All the elements found in the location are ignored by default. You have to add them explicitly if you want to use them.

    Use the tag ADD with the filename (without the path) of the element inside.

Example :

CopyXML
<!-- All models except the SYSREQ model -->
<MODELSSELECTION PATH="Models" WORKSPACEPATH="D:\Workspaces\Repository\Test\" RULE="AddAllThenIgnore">
    <IGNORE>SYSREQ.xml</IGNORE>
</MODELSSELECTION>
<!-- All tools -->
<TOOLSSELECTION PATH="Tools" WORKSPACEPATH="" RULE="AddAllThenIgnore" />
<!-- No renderers from current workspace -->
<RENDERERSSELECTION PATH="Renderers" WORKSPACEPATH="" RULE="IgnoreAllThenAdd" />
<!-- Renderer CoolRenderer from an external workspace -->
<RENDERERSSELECTION PATH="Renderers" WORKSPACEPATH="D:\AnotherWorkspace" RULE="IgnoreAllThenAdd">
    <ADD>CoolRenderer.xrd</ADD>
</RENDERERSSELECTION>

Activate Baseline Mechanism

The workspace definition file (XWS) controls the activation of the baseline mechanism. Baseline has no prerequisite on models. It can be used on any project. To activate baseline mechanism, just give the name of the 1st baseline you will work on in the BASELINE tag of the workspace definition file.

CopyXML
<BASELINE>
    Name of my baseline
</BASELINE>

Use the splash screen

The splash screen is activated with the tag named SPLASHSCREEN. This tag has one attribute named DURATION.

The attribute DURATION determines the splash screen's timeout in seconds. If the user doesn't click on the splashscreen before the timeout, the splash screen disappears automatically. Otherwise, it will disappear immediatly after the click.

The splash screen can be any bitmap file with the following extension : BMP, JPG, PNG, GIF. The path of the bitmap file must be placed in the TAG. Path may be relative to the workspace location.

Example :

CopyXML
<SPLASHSCREEN DURATION="3">
    Bitmaps/myscreen.jpg
</SPLASHSCREEN>

This will display the picture of Bitmaps/myscreen.jpg during 3 seconds when the workspace starts.

Background image

You can set the background picture of the main form of MADCAT using the tag BACKGROUNDIMAGE. This tag supports one attribute named LAYOUT.

The LAYOUT specifies the way the picture shall be displayed in the main form background. You have different values :

  • stretch : image is streched to fit the window's size
  • tile (default) : image is tiled to cover the entire window's background
  • zoom : image is zoomed (aspect is preserved) to fill the entire window's background
  • center : image is centered in the window's background. Its size is preserved.
  • none : image is aligned on the top left corner of the window. Its size is preserved.
CopyXML
<BACKGROUNDIMAGE LAYOUT="stretch">
    bitmaps/bg.jpg
</BACKGROUNDIMAGE>

Help File

Using the tag HELPFILE, you can specify a help file which must be opened by MADCAT when the user hits the F1 key or select Help from the main menu.

CopyXML
<HELPFILE>
    myhelpfile.hlp
</HELPFILE>

Application Information

Use the tags AUTHOR, ICON and DESCRIPTION to describe and decorate your application. The ICON may be any bitmap file having one of these extensions : ICO, GIF, PNG, BMP, JPG. AUTHOR and DESCRIPTION contain free text.

CopyXML
<AUTHOR>My name here</AUTHOR>
<ICON>bitmap/appicon.jpg</ICON>
<DESCRIPTION>My app provides all the services you need</DESCRIPTION>

Data is displayed in the "About" box of the application.


Models

[image]

MADCAT User Guide
Models
Send Feedback
MADCAT User Guide v1.2.2

Models are XML files which are read by the MADCAT to manage your databases. They control the way input forms will be generated, items will be stored, and so on... They are the base of your workspace

Models Management

You may create as many model files as you want. A database will be generated and maintained for each of them. You can also modify them at any time. The MADCAT can handle models' changes without any problem. Items are automatically synchronized when you edit them : You added a new attribute in the model, older items will automatically inherit this new attribute when you will edit them. You removed an attribute from the model, older items will keep their attribute but you won't see it anymore in the input forms and other MADCAT's windows. If you restore it, values of items will be modifiable again. You can do errors without loosing your precious data.

Models Content

A database can contain the following elements :

  • Items : Basic entity on which users can perform actions. They have attributes.
  • Series : Series of items dedicated to the generation of charts.
  • Folders : Elements used to organize the items, links and queries of your database.
  • Queries : Special elements which acts like folders where the content is a list of items selected by a given query defined by an XPath expression. Items are not physically stored in this kind of folder but elsewhere in the database.
  • Links : Special elements used to add multiple instances of the very same item at different places in your database. Data is not duplicated in the database but in the reports and the tools contexts.

Human Machine Interface Management

Models control the HMI of MADCAT on the following points :

  • Icons of database, items, series, folders, queries and links
  • Type of items' attributes and display options of these types
  • Actions authorized on items (buttons of the tool bars)
  • Triggers on user's actions
  • Multiview mode configuration for explorer windows

This control is done through XML elements which are :

  • ITEM
  • SERIES
  • FOLDER
  • QUERY
  • LINK


Items

[image]

MADCAT User Guide
Items
Send Feedback
MADCAT User Guide v1.2.2

Control items' appearence

The ITEM element can control the way items will be displayed in the application. Many attributes are available to do that :

  • NAME : Defines the name used by users to identify the item
  • ICON : Defines the icon used by MADCAT to decorate the item
  • RENDERER : Defines the prefered renderer to be used to display the item's children
  • RENDERMODE : Defines the prefered display mode of the prefered renderer to be used to display the item's children
  • RENDEROPTIONS : Defines the options for the prefered display mode of the prefered renderer to be used to display the item's children
CopyXML
<ITEM NAME="My item" NODENAME="ITM" ICON="bitmap/item.png" RENDERER="ListView" RENDERMODE="Details" RENDEROPTIONS="">
    <ATTRIBUTE NAME="NAME" DESC="Name of the item" TYPE="STR"/>
</ITEM>

This example defines one type of item named "My item". This name will appear everywhere it is needed in the application to identify it. It has one icon coming from the file "Bitmap/item.png". All the items created with this definition will have the same type name and the same icon.

Control items' icon

This is new with version 1.2

The icon of an item can be dynamically set by an attribute of this item. Just enter the name of the attribute prefixed with a '@' instead of a filename in the attribute 'ICON' and then the default renderers of the MADCAT will read the attribute value and use it as a filename for an icon.

Here is an example :

With this definition,

CopyXML
<ITEM NODENAME='IRS' NAME='Interface' ICON='@IMAGE'>
    <ATTRIBUTE NAME='PUID' DESC='Identifier' TYPE='STR'/>
    <ATTRIBUTE NAME='TITLE' DESC='Title' TYPE='STR'/>
    <ATTRIBUTE NAME='IMAGE' DESC='Image' TYPE='BMP'/>
</ITEM>

the item 'IRS' will have the icon specified by the attribute 'Image' :

Item Dynamic Icon

Control database content

The ITEM element can control the way items are stored in the database :

  • NODENAME : Defines the name of the Xml element which will be created in the database to save the values of the attributes entered by the user

The example defined above will be stored in the database as a Xml element 'ITM' each time the user will request an item creation with this definition. It has one Xml attribute named "NAME" where the name of the item will be stored in the database. So if the user creates one item with this definition and enters "Test" as a name, the database will contain the following :

CopyXML
<ITM NAME="Test"/>

Another example :


Attributes

[image]

MADCAT User Guide
Attributes
See Also Send Feedback
MADCAT User Guide v1.2.2

Attributes of Xml elements of the database are defined by ATTRIBUTE elements in the models. ATTRIBUTE elements shall be defined within an ITEM element. Only ITEM elements can have ATTRIBUTE elements. ATTRIBUTE elements control the kind of data which can be stored and the way it is displayed in the application.

Attribute types

In order to manage the values stored in the database, MADCAT must know the basic type of each value. This type is given by the attribute TYPE of ATTRIBUTE element. By default, MADCAT provides several basic types which are :

  • STR : The value is a string (array of characters)
  • NUM : The value is a number (hexadecimal, integer or float, signed or unsigned)
  • BMP : The value is the path of a bitmap file in a filesystem
  • FILE : The value is the path of a file in a filesystem
  • DIR : The value is the path of a folder in a filesystem
  • DATETIME : The value is a date and a time
  • IPADDR : The value is an IP v4 address
  • BOOL : The value is a boolean (True or False)
  • ENUM : The value is one value taken from a predefined list
  • COLOR : The value is a color

Grouping attributes

When the number of attributes for one item is important, it can be useful to group them by category. To do this, MADCAT provides a specific type named "GRP" which will not store any data in the database but simply group a list of attributes in the input form used by the users to enter values in attributes.

Type input controls

Choosing the right type is very important. Each type has a dedicated input control designed to ease the user inputs and reduce contraints. For example, MADCAT provides numerous way of selecting numbers which can avoid the user from typing them with the keyboard : it has sliders, rotary buttons, ... For Date and time, user can pick values in a calendar... The table below shows the controls offered by MADCAT :

Type | Input control | String display | Bitmap display | Xml display
STR | A text box | The raw value | N/A | N/A
NUM | A text box or a graphical control (depends on options) | The formatted numeric value | When gauge is active, a gauge | N/A
BMP | A text box with a preview panel and a browse button | The path of the bitmap file | N/A | N/A
FILE | A text box with a browse button | Path of the file | N/A | N/A
DIR | A text box with a browse button | Path of the directory | N/A | N/A
DATETIME | A text box with a calendar pop-up | The date/time in dd/mm/YYYY hh:mm:ss format | N/A | N/A
COLOR | A solid filled box with a color picker pop-up | The color coded into HTML #RRGGBB | A solid filled box with the color | N/A
ENUM | A combo box, a group of check box or a list box (depends on options) | The label of the selected value | N/A | N/A
IPADDR | A serie of 4 text boxes with up/down buttons | The IP address in IPv4 format : xxx.xxx.xxx.xxx | N/A | N/A
BOOL | A check box or a graphical switch or led (depends on options) | YES or NO | A led | N/A

Creating new types

MADCAT can be easily extended by adding new type handlers. A dedicated interface is provided if you want to code your own type handler and enhance the interface of your application.

The type handler is in charge of :

  • Coding/Decoding the string value stored in the database
  • Displaying the decoded value in the application interface (as a string, a bitmap or an Xml element)
  • Providing a dedicated input control adapted to the nature of the data
  • Filtering items
  • Sorting items

See Also

Other Resources

Samples of input controls in relation with types of attributes and their options.


Triggers

[image]

MADCAT User Guide
Triggers
Send Feedback
MADCAT User Guide v1.2.2

Element used to bind an action to an item or a folder and a specific user event. Actions are treatments performed by a tool on one or several items (or folders). When the end-user executes the expected event of a trigger on the item (or folder), MADCAT runs the action attached to the trigger. The end-user can't control this execution but it can activate/deactivate triggers of a database by using the configuration panel of MADCAT.

What kind of event can be triggered ?

MADCAT manages the following triggers :

Trigger Name | Fired after | Fired before | Usage
BEFEDIT | The user clicks on the "Edit" button to edit an item | The edit form is active | Can be used to block item edition if necessary
AFTEDIT | The user commits his changes | Xml data is actually updated | Can be used to cancel the changes if necessary
BEFLINK | The user clicks on the "Create link" button | Drop-down menu for target selection opens | Block link creation if necessary
AFTLINK | The user selects a target | The Xml data is actually updated | Cancel operation if target is not correct
BEFCREATE | The user clicks on the "Create item" button | The edit form is active | Block creation if necessary
AFTCREATE | The user commits his changes | Xml data is actually updated | Cancel the creation if necessary
BEFDEL | The user clicks on the "Delete item" button | Xml data is actually updated | Block the deletion if necessary
SELECT | The user clicks on an item | The selection is actually updated | Update/refresh something in relation with the user selection
ACTIVATE | The user double clicks on an item | The root item is actually changed | Update/refresh something in relation with the user selection OR block the navigation in a sub-folder or an item
DROP | The user drops data on an item | The drop action is over | Run an action on an item using the dropped item
TIMER | A timer reachs its deadline | The timer is armed for another cycle | Run an action periodically without user interaction
Note
A trigger can be set multiple times for an item, a series or a folder if you want to attach several actions to the same event.

Triggers configuration

In MADCAT, users can select the triggers they want to active. The list of triggers defined in a model is available in the configuration panel of MADCAT by clicking the icon of the corresponding database. If database's model defines triggers, they will be listed in the configuration form and the user will be able to active/deactive the triggers of the database. By default, triggers are active.


Actions

[image]

MADCAT User Guide
Actions
Send Feedback
MADCAT User Guide v1.2.2

Element used to bind an action to an item or a folder. Actions are treatments performed by a tool on one or several items (or folders). When the end-user selects an item which has ACTION elements in the model, MADCAT activates the buttons of the tool bar which are attached to the actions defined by these elements (it activates also the action in the contextual menu of the item). The action is not run automatically but the end-user can run it by pressing the button.

Associate actions to items

An action can be easily associated to a type of item in models. Just add an Xml element named ACTION within the Xml element ITEM in a model. The attribute NAME of ACTION gives the name of the action. If this action exists (i.e. a tool declaring this action in its definition file has been succesfully loaded), the button of this action will be active each time the user will select an item defined with the ITEM element of the model.

For example, if the model has the following entries :

CopyXML
<ITEM NAME='Test' NODENAME='TEST'>
    <ACTION NAME='RunProc'/>
</ITEM>

and the workspace has a tool definition file like this :

CopyXML
<TOOL NAME='My Tool' CLASSPATH='mytool.dll'>
    <ACTION NAME='RunProc' DESC='My procedure'/>
</TOOL>

The tool bar of the main form will have one button named "My procedure". By default, it will be grayed (disabled). If the user creates an item using the model named "Test" and selects it, the button will be active and the action named "MyProc" will be executed if the users clicks on it. If the tool definition file doesn't exist or action name is different, the action is not linked to the item type. Model and tool definition file can be modified at any time without any loss of data. This feature only acts on the humain interface of MADCAT.


Multiview

[image]

MADCAT User Guide
Multiview
Send Feedback
MADCAT User Guide v1.2.2

This is a new feature of the MADCAT v1.2.

The automatic configuration of the multiview mode of explorer windows can be done by the models. You can setup a multiview configuration in the definitions of any items, folders or series by using the MULTIVIEW element. See MULTIVIEW Definition. When a definition has a multiview configuration, users can change the number of visible forms and their positions but his changes won't be saved. Definition's configuration will automatically be reused next time.

Also, in these definitions, you can also filter the content of each form. This is very useful when an item has several types of children. In this case, you can setup a form for each type and activate a dedicated renderer in each of them.

So in one click, the display will be setup automatically for the best user experience.

For a series definition, one good multiview configuration is :

  • the tabular series renderer docked at the top border with autohide feature

  • the graphical series renderer filling the entire multiview area

With this configuration, when you select a series, the explorer will show you the charts built with the series data and the user will be able to move his mouse cursor to the top border to open the table of values and see detailed data of the charts.

CopyXML
<SERIES NODENAME='OBJ' NAME='Objectives' RENDEROPTIONS='orientation=vertical'>
    <MULTIVIEW>
        <VIEW TITLE='Table of values' RENDERER='TABSERIES' CONTENT='' POSITION='top' HEIGHT='300'/>
        <VIEW TITLE='Chart settings' RENDERER='GSPrefsRenderer' CONTENT='' POSITION='left' AUTOHIDE='true'/>
        <VIEW TITLE='Chart' RENDERER='GSRENDERER' CONTENT='' POSITION='fill'/>
    </MULTIVIEW>
    <INDEX NAME='DATE' DESC='Date' TYPE='DATETIME'/>
    <ATTRIBUTE NAME='EXPACCEPTED' DESC='Nb accepted requirements' TYPE='NUM'/>
    <ATTRIBUTE NAME='EXPVALIDATED' DESC='Nb validated requirements' TYPE='NUM'/>
    <ATTRIBUTE NAME='EXPREJECTED' DESC='Nb rejected requirements' TYPE='NUM'/>
    <ATTRIBUTE NAME='EXPDRAFT' DESC='Nb draft requirements' TYPE='NUM'/>
</SERIES>

When the user selects a series of type 'Objectives', the renderer area will be configured like this :

Explorer Multiview Config Example 4

The list of values can be hidden in the top edge, to get a bigger chart :

Explorer Multiview Config Example

Both the table of values and the chart settings are masked and can be opened by clicking on their tab :

Explorer Multiview Config Example 2
Explorer Multiview Config Example 3
Explorer Multiview Config Example 5


Folders

[image]

MADCAT User Guide
Folders
Send Feedback
MADCAT User Guide v1.2.2

Element used to define a folder of a database. Folders are entities which can't be created/edited/deleted by the end-user. They are built and managed automatically by MADCAT. If an ITEM has one folder, the folder will be created when the ITEM is created by the end-user.

Root folders

Root folders are folders placed on the top of the database's hierarchy. These folders are automatically created when the database is initialized or started.

Note
If you change your model to add new root folders, the existing database will be updated when opened.

Can the users add folders ?

Because a database can have numerous items, users can create/edit/delete their own folders inside the database. These folders can be placed anywhere within the hierarchy defined by the model. For MADCAT, when applying model rules concerning ITEMS and LINKS, user folders are "transparent" : this means that the ITEMS (or LINKS) applicable to the parent element defined by the model are applicable.

Note
User folders are always stored using an Xml element named "FOLDER" in the database. Because of this, the name "FOLDER" is reserved and shall never be used in any model.


Links

[image]

MADCAT User Guide
Links
Send Feedback
MADCAT User Guide v1.2.2

Element used to define a link to one item of a database. Links are entities which can be created/deleted/selected by the end-user and actions can be performed on them. They are shortcuts (or references) to other items created by the end-user in the database.

Defining a LINK in a model just activate the possibility for the end-user to create links to specific items in one item or one folder. This will avoid the classic copy of the item. Data is never duplicated.

When the end-user prints a link or an item or a folder which has links inside, MADCAT resolves links and automatically replace the link by the item it refers to. Using the same principle, when a tool performs an action on an item or a folder which has links inside, MADCAT resolves the links and the tools will directly "see" the XML data of the target item instead of the link itself. They can be seen as phantom items as their data is never seen by the end-user or tools. Their content is dynamically replaced by the data of the target item (like if the target were actually a child of the printed item for example) when needed.

How reports manage links ?

Before performing Xsl transformation, links are replaced by the Xml of the target element. Doing so enables multiple instances of the same item to be processed as if they were actual copy of the same Xml elements from the Xsl point of view. This can be checked easily when viewing a report in raw Xml mode (before HTML conversion with Xsl).

links in report

How tools manage links ?

Just like reports, data context for tools contains no links because they are automatically replaced by their respective targets before the context is passed to the tool.

In the other hand, tools can create links in the database. In this case, link is not converted because it is assumed that the tool knows the Xml target !

How to get to the target ?

MADCAT explorer window has a specific button to follow a link immediatly. The explorer moves to the target :

How to find links from the target ?

It is very simple to find if links exist for a given target. Use the MADCAT interface :


Queries

[image]

MADCAT User Guide
Queries
Send Feedback
MADCAT User Guide v1.2.2

Element used to define a dynamic query. Queries are used to dynamically execute a XML query (using XPath expressions) and display the result in a MADCAT Explorer window. A query will never produce any data in the database. This is only used for dynamic display on screen. They behave like folders with dynamic content. For example, you can use queries to list important items (faulty items, hot items, etc...) to the end-user in a specific folder of your database. The end-user can't change the content of a query result but he can edit items displayed inside.

Example of a QUERY

Help documentation built with Sandcastle Help File Builder

Send comments on this topic to contact@themadcat.fr

(c)2012,2013 Eric Pageron


Series

[image]

MADCAT User Guide
Series
Send Feedback
MADCAT User Guide v1.2.2

This is a new feature of the MADCAT v1.2.

This is a new element which will facilitate the management of series of values. A series is set of items sharing a space of index values. Two different items can't have the same index value. Items can have several attributes. Each attribute will be considered as a series of values using the index.

How to manage series ?

It comes also with a dedicated edit form :

The index is shown and controlled on the top. When you select an index value, the MADCAT shows the corresponding item's values if it exists. Otherwise, it enables the "Add" button to let you create a new item for the current index.

When an item is displayed, you can delete it or edit it. Arrows are displayed near the index : use them to move forward or backward in the index values having items.

Series Edit Form

Items of a series are managed like classical and standalone items. If you browse a series in the explorer window, you'll see the items in it and be able to delete them, edit them, see their history, print them like classical items.

Note
Note that the index value is not visible in the edit form, so it can't be edited. The index is a part of the identifier of the item; so it can't be changed. The other thing you can't do is creating new items. You have to edit the parent series node to enter new items.

Dedicated renderers

Series come with 2 dedicated renderers :

  • The tabular renderer which shows the series in a table. Index may control rows or columns.

    Series Table Example

  • The graphical renderer which generate charts : one chart per attribute.

    Series Chart Example

Each chart can be drawn using dots, curves or bars. Charts can be stacked, merged, superimposed or drawn separately in tabs or scrollable pages.

Navigation through series

Series can be seen as folders in the navigation tree of the explorer windows or not. Control the behaviour of the navigation tree with the configuration panel of the MADCAT. Double-click the model icon and then select the right option "Maximum depth for tree view".

How to series are saved in Xml files ?

In the project, series data are saved like this :

  1. A Xml element is created using the nodename of the series with a 'S' at the end.

  2. Then each item is created inside this element using the nodename of the series. The ID of the item contains the value of the index followed by '@' then the ID of the series element :

    INDEX@ID

Here is an example of Xml data for a series. Index is the attribute 'DATE'. The definition is named 'OBJ' in the model.

CopyXML
<OBJS NAME="New Series" ID="13,/REQM">
  <OBJ EXPACCEPTED="3" EXPVALIDATED="8" DATE="10/06/2012 23:04:25" ID="10/06/2012 23:04:25@13,/REQM" EXPDRAFT="3" EXPREJECTED="1" TYPE="" />
  <OBJ EXPACCEPTED="2" EXPVALIDATED="2" DATE="11/06/2012 23:04:25" ID="11/06/2012 23:04:25@13,/REQM" EXPDRAFT="3" EXPREJECTED="1" TYPE="" />
  <OBJ EXPACCEPTED="3" EXPVALIDATED="1" DATE="12/06/2012 23:04:25" ID="12/06/2012 23:04:25@13,/REQM" EXPDRAFT="1" EXPREJECTED="1" TYPE="" />
  <OBJ EXPACCEPTED="4" EXPVALIDATED="5" EXPREJECTED="2" EXPDRAFT="1" DATE="13/06/2012 23:04:25" ID="13/06/2012 23:04:25@13,/REQM" TYPE="" />
  <OBJ EXPACCEPTED="2" EXPVALIDATED="2" EXPREJECTED="3" EXPDRAFT="3" DATE="16/06/2012 23:04:25" ID="16/06/2012 23:04:25@13,/REQM" />
</OBJS>


Inheritances, Polymorphism and References

[image]

MADCAT User Guide
Inheritances, Polymorphism and References
Send Feedback
MADCAT User Guide v1.2.2

Inheritance

This is a new feature of the MADCAT v1.2.

To increase the possibilities in your workspaces without heavy models definitions, inheritance has been added in the MADCAT.

It allows you to decline a base definition of an item, series or folder to a multiple of other definitions. So base actions, attributes or display configuration can be setup for once in a model definition and then reused infinitely in many definitions by inheritance.

The system works like C++ inheritance : when a definition inherits another, the parent definition can still be used to create items, series or folders. But a child definition can override its parent. In this case, only the child can be used to create elements. The parent definition has no direct effect on the workspace and is not visible for the user. It used only for model definitions.

Inheritance is defined using the element INHERITS. When the attribute OVERRIDE of the element is set to "YES", the parent definition defined by the attributes NODENAME and DATAMODEL won't be used by the MADCAT to create elements in the database. In other words, the user won't see this definition in the interface and he will only see the child definitions which inherits it.

For example, the following definition inherits the definition named 'REQBASE' :

CopyXML
<ITEM NAME="Technical Requirement" NODENAME="TECHREQ" ICON="" STYLESHEET="" RENDERER="" RENDERMODE="" RENDEROPTIONS="">
  <ATTRIBUTE NAME="RATIONALE" DESC="Rationale" HELP="" TYPE="TXT" OPTIONS="lines=5" />
  <ATTRIBUTE NAME="UPREQ" DESC="Upward Requirements" HELP="" TYPE="ItemTypeHandler" OPTIONS="" />
  <INHERITS NODENAME="REQBASE" DATAMODEL="SYSREQ" OVERRIDE="YES" />
</ITEM>

The definition named 'REQBASE' is :

CopyXML
<ITEM NAME="BaseRequirement" NODENAME="REQBASE" ICON="" STYLESHEET="" RENDERER="" RENDERMODE="" RENDEROPTIONS="">
  <ATTRIBUTE NAME="TITLE" DESC="Title" HELP="" TYPE="STR" OPTIONS="mandatory=yes" />
  <ATTRIBUTE NAME="TEXT" DESC="Text" HELP="" TYPE="TXT" OPTIONS="mandatory=yes,lines=5" />
  <ATTRIBUTE NAME="VERS" DESC="Version" HELP="" TYPE="NUM" OPTIONS="mandatory=yes,mini=1,maxi=99" />
  <ATTRIBUTE NAME="STATUS" DESC="Status" HELP="" TYPE="ENUM" OPTIONS="mandatory=yes">
    <ENUM VALUE="draft" />
    <ENUM VALUE="in review" />
    <ENUM VALUE="validated" />
    <ENUM VALUE="obsolete" />
  </ATTRIBUTE>
</ITEM>

Finally the definition of 'TECHREQ' is equivalent to :

CopyXML
<ITEM NAME="Technical Requirement" NODENAME="TECHREQ" ICON="" STYLESHEET="" RENDERER="" RENDERMODE="" RENDEROPTIONS="">
  <ATTRIBUTE NAME="TITLE" DESC="Title" HELP="" TYPE="STR" OPTIONS="mandatory=yes" />
  <ATTRIBUTE NAME="TEXT" DESC="Text" HELP="" TYPE="TXT" OPTIONS="mandatory=yes,lines=5" />
  <ATTRIBUTE NAME="VERS" DESC="Version" HELP="" TYPE="NUM" OPTIONS="mandatory=yes,mini=1,maxi=99" />
  <ATTRIBUTE NAME="STATUS" DESC="Status" HELP="" TYPE="ENUM" OPTIONS="mandatory=yes">
    <ENUM VALUE="draft" />
    <ENUM VALUE="in review" />
    <ENUM VALUE="validated" />
    <ENUM VALUE="obsolete" />
  </ATTRIBUTE>
  <ATTRIBUTE NAME="RATIONALE" DESC="Rationale" HELP="" TYPE="TXT" OPTIONS="lines=5" />
  <ATTRIBUTE NAME="UPREQ" DESC="Upward Requirements" HELP="" TYPE="ItemTypeHandler" OPTIONS="" />
</ITEM>

The advantage is that all evolutions done on 'REQBASE' are automatically applied to 'TECHREQ'.

Note
Inheritance works with ATTRIBUTE, ACTION, TRIGGER and all other children (ITEM, FOLDER, ...) of the parent definition.

Polymorphism

This is a new feature of the MADCAT v1.2.

Now different models can have the definitions with the same name (for items, folders and series). When MADCAT detects duplicate definitions within a workspace, it merges them into a single definition. Actions, attributes, triggers and children elements are merged into the same parent definition.

For example, if one model has the following definition for folder 'TRIGGERS' :

CopyXML
<FOLDER NAME='Triggers allowed on the item' NODENAME='TRIGGERS'>
    <ITEM REFERSTO='TRIG'/>
</FOLDER>

and another model has the following definition for folder 'TRIGGERS' :

CopyXML
<FOLDER NAME='Triggers allowed on the item' NODENAME='TRIGGERS'>
    <ITEM REFERSTO='ITEM'/>
    <ITEM REFERSTO='LINK'/>
</FOLDER>

If both models are loaded in the same workspace, the resulting definition will be :

CopyXML
<FOLDER NAME='Triggers allowed on the item' NODENAME='TRIGGERS'>
    <ITEM REFERSTO='TRIG'/>
    <ITEM REFERSTO='ITEM'/>
    <ITEM REFERSTO='LINK'/>
</FOLDER>

References

Inside a model, when you want to define an element with child ITEM elements that have already been defined inside the model, just put references for each child instead of duplicating their complete definition into the element.

See the Xml attribute REFERSTO of ITEM for more details.

In this example, TRIG, ITEM, LINK, MFOLDER and QUERY are ITEM elements defined in the same model. The folders defined here will contain these items.

CopyXML
<FOLDER NAME='Triggers allowed on the item' NODENAME='TRIGGERS'>
    <ITEM REFERSTO='TRIG'/>
</FOLDER>
<FOLDER NAME='Allowed child elements' NODENAME='CHILDREN'>
    <ITEM REFERSTO='ITEM'/>
    <ITEM REFERSTO='LINK'/>
    <ITEM REFERSTO='MFOLDER'/>
    <ITEM REFERSTO='QUERY'/>
</FOLDER>


Tools

[image]

MADCAT User Guide
Tools
Send Feedback
MADCAT User Guide v1.2.2

A tool is an extension of MADCAT which performs treatments on data. It can be an external executable file (EXE) or a dedicated assembly (DLL) compliant with MADCAT API. It uses inputs of the end-user and XML data to execute a specific (or several) action(s) and produce a determined result. When the tool is an external executable file, possibilities are limited. MADCAT just runs the tool with several command line arguments taken from the end-user selection and inputs and then wait for the end of its execution. Monitoring, control of the process totally depend on the executable file.

When the tool is an assembly, possibilities are very large and a high level of integration is possible. The development of a tool requires a good knowledge of managed C++ (CLR) and .Net framework assemblies. You also need to be familiar with MADCAT API and the tool interfaces. By default, MADCAT installation program installs a specific wizard for Visual C++ Express. Using this wizard, you will rapidly start a new project to build your tool. The prefered entry is the XML data provided by the database i.e. the items selected by the end-user in MADCAT explorer window. MADCAT offers also dialog boxes which can be used to offer options to the user before performing the treatment.

How actions are executed

A treatment is named an action is MADCAT. An action is composed of 2 different phases :

  • The initialization phase : This is the very first part of the treatment. The end-user has just selected items and run the action by pressing the button attached to the action. During this phase, the tool can use dialog boxes to ask more questions to the user before performing the action. This can be additional infos, options, acknowledgements, warnings, etc... When this phase is over, the tool can choose to :
    • cancel the action : When the tool cancels the action, MADCAT won't enter the 2nd phase. Execution is over.
    • schedule the action : When the tool wants to proceed but can't do it now because one of the required ressource is not available (used by another running action for example)
    • proceed : When the tool decides to proceed now, MADCAT enters the 2nd phase :
  • The execution phase. The tool should never wait for a user input during this phase except for fatal errors which will end the action. MADCAT may display a progress window and the tool shall regularly generate messages or update the progress status in order to allow process monitoring by the end-user. During this phase, the tool shall :
    • interrupt the action if an error occurs (fatal)
    • generate non-blocking information or warning messages if necessary
    • update progress status periodically
    • perform the requested treatment using only the input data provided by the end-user during the initialization phase. This treatment shall be deterministic (the same inputs shall produce the same result).

Automatically MADCAT will :

  • record all the inputs defined in the initialization phase
  • record all the messages and progress statuses generated during the execution phase.

MADCAT supports several modes of execution for one action :

  • background task (end-user can continue working in your application while the action is running)
  • synchronous task (end-user must wait for the end before working in the application again)

Your tool may authorize the following events :

  • End-user pauses (and resumes) an action : The tool shall interrupt the process and be able to resume it instantly.
  • End-user cancels an action : The tool shall be able to stop the process definitely instantly.
  • End-user restarts an action : The tool shall be able to restart the 2nd phase without performing the initialization phase again. The same inputs are used but the execution phase shall start from zero.

All these options are completely dependent of the design of the tool itself. So, to integrate your tool correctly into its interface, MADCAT needs a complete description of the tool and the actions it can perform. This is done by writing the Tool definition file (XTL file). The XTL file is a simple XML file which must be located in the "Tools" folder of your workspace. The XML file shall be compliant with the following schema :


Tool Definition File

[image]

MADCAT User Guide
Tool Definition File
Send Feedback
MADCAT User Guide v1.2.2

Practically a tool is a DLL (Dynamic Link Library) with a definition file having a XTL extension. This definition file controls the way MADCAT displays and executes the actions supported by the tool : it gives the following information :

  • Name of the tool
  • Icon of the tool
  • Description of the tool
  • Path to the DLL or EXE file
  • List of actions supported by the tool. For each action, you can provide the name, the icon, the description and the execution settings (see below)

Using tool in library

This is the most powerful mode. The library is developed using MADCAT's API. The tool integration is at the highest level. See references for more informations about tool development with MADCAT's API.

Using tool in executable file

This is the most simple mode. The executable is run using the command line mode. Integration with MADCAT is limited to passing arguments to the command line on one hand and catch executable's output on the other hand. But it is also the most opened mode, you can control a tool not previously made for MADCAT from your workspace.

Actions in a tool (in DLL mode only)

Execution of actions can be controlled by several parameters :

  • Background mode : Action is executed in a specific thread. End-user can continue working in MADCAT while action is running
  • Read-only mode : Action can't modify project's data
  • Cancelable : End-user can cancel an in-progress action
  • Suspendable : End-user can pause/resume an in-progress action
  • Endless action : Action has no end. It must be canceled by the user
  • Show progress window : Progress window is automatically displayed when action starts
  • Re-entrant : If set to Yes, same action can be run multiple times in parallel. Otherwise, MADCAT will automatically schedule the action at the earliest moment depending on the end of the currently running threads
  • Multiselect : If set to yes, action can be executed on more than one item at a time. Otherwise, MADCAT will schedule the action once for each item

These settings are defined once for all by the designer of the tool. Changing these settings without changing the tool itself may produce unpredicable results.

Example

CopyXML
<TOOL NAME='WORKSPACEGENERATOR' LABEL='Tool for workspace editor' DESC='Generates your workspace' PATH='Tools/WorkspaceEditorTool.dll'>
    <ACTION NAME='GENERATE' DESC='Generate Workspace' OPTIONS='cancelable=no,suspensible=no,permanent=no,multiselect=no,background=no,showdetails=no,readonly=no,reentrant=no'/>
    <ACTION NAME='REGENERATION' DESC='Regenerate Workspace' OPTIONS='cancelable=no,suspensible=no,permanent=no,multiselect=no,background=no,showdetails=no,readonly=no,reentrant=no'/>
</TOOL>


Renderers

[image]

MADCAT User Guide
Renderers
Send Feedback
MADCAT User Guide v1.2.2

A renderer is an extension of MADCAT which extends the graphical interface of the application. By default, MADCAT has 3 renderers :

  • List view renderer. This renderer displays items like window explorer displays files. It has 3 modes : icons, tiles and details modes.
  • Vertical view renderer. This renderer displays items in columns. Attributes are the lines of the table.
  • Baseline view renderer. This renderer can display all the values of items found in the different baselines of your project. This renderer is activated only if baseline mode is active.

If these default views are not adapted to your application, you can build your own renderer and then control the way items can be displayed and selected by the end-user. A renderer can :

  • control the right panel of the explorer window (the panel which is on the right of the explorer tree view). This area is totally under renderer's control which shall use .Net framework controls (see assembly System::Windows::Forms)
  • control the content of the 2nd part of the renderer tool bar of the explorer window. A renderer can add any controls it needs in this bar.

A renderer shall :

  • update its display any time the user creates/edit or delete one or several items.
  • forward any selection performed by the user in the renderer area to MADCAT
  • if renderer manages baselines, respect the baseline logic of MADCAT in its display area.
  • never modify the content of the database

The development of a renderer requires a good knowledge of managed C++ (CLR) and .Net framework assemblies. You also need to be familiar with MADCAT API and the renderer interfaces. By default, MADCAT installation program installs a specific wizard for Visual C++ Express. Using this wizard, you will rapidly start a new project to build your renderer. In final, your renderer shall be an assembly (a DLL) with a XRD file (this file is also initialized by the Visual C++ wizard). The XRD file is a Renderer Definition file for MADCAT. It is used to integrate the renderer into the graphical interface of MADCAT. DLL and XRD shall be located in the "Renderers" folder of your workspace. This file is an XML file which shall follow the following schema :


Default Renderers

[image]

MADCAT User Guide
Default Renderers
Send Feedback
MADCAT User Guide v1.2.2

MADCAT provides several renderers by default. Some are directly embedded into MADCAT's executable file, others are standalone DLLs.

This topic contains the following sections.

  • Listview Renderer
  • Vertical Renderer
  • Baseline Renderer
  • Tabular Series Renderer (new with version 1.2)
  • Graphical Series Renderer (new with version 1.2)
  • Graphical Series Preferences (new with version 1.2)

Listview Renderer

This renderer supports 3 modes :

  • Icons : Elements are displayed with big icons. The value of the 1st attribute of the element is displayed under the icon
  • Tiles: Elements are displayed with big icons. The value of the 1st attribute of the element is displayed under the icon along with its type description
  • Details : Elements are displayed with small icons. The values of the attributes of the elements are displayed in columns. One column per attribute. They can be sorted or filtered. Columns order can be changed. Columns can be masked or displayed.

It is the most common way of rendering items. It acts like the windows explorer with files and folders.

Vertical Renderer

This renderer supports 1 mode. Elements are shown in column. Attributes are displayed in lines. It is useful when you want to compare items' attributes.

Baseline Renderer

This renderer supports 1 mode. Elements are shown in group. Columns are different baselines and values of each baseline are shown in columns. It is useful to check differences between baselines.

Tabular Series Renderer (new with version 1.2)

Note
Standalone DLL. Must be added manually to your workspace with its definition file (.XRD)

Shows series in tables.

When the selected item is a series, the renderer shows the series' values. When the selected item is a folder or an item having series in its children, the renderer shows all the series found in seperate tables. Orientation of the table can be controlled by the render options parameter named "orientation". Possible values are :

  • horizontal (default)

  • vertical

Series Table Example

Graphical Series Renderer (new with version 1.2)

Note
Standalone DLL. Must be added manually to your workspace with its definition file (.XRD)

Shows series in charts.

When the selected item is a series, the renderer shows the series' values in charts. Otherwise, nothing is displayed. Appearance of the charts is controlled with another renderer named the "Graphical Series Preferences" (see below). When you change a parameter of the appearance, charts are updated automatically. All your changes are saved in the user profile so that it can be recalled anytime the user selects the same series again. All the appearance preferences are saved when you leave the current workspace.

The graphical area of the renderer can be saved to a bitmap file (JPG, PNG, TIF, BMP, GIF or WMF) or copied to the clipboard.

Series Chart Example

Graphical Series Preferences (new with version 1.2)

Note
Standalone DLL. Must be added manually to your workspace with its definition file (.XRD)

This is not really a renderer as it doesn't render the series or items of your database but the preferences used by the graphical series renderer to generate charts.

Preferences are attached to series. Each series can have its own preferences.

This renderer controls the appearance of the current graphical series displayed in the explorer window.

Note
It is highly recommended to use the multiview mode to activate both the "Graphical Series Preferences" and the "Graphical Series Renderer" renderers. In this mode, you can interactively change the charts preferences.

Here are some example of charts :

Stacked curves

Curves are stacked one over another on the same layer.

Note
When curves are drawn on the same layer, a rectangle with captions appears on the chart. This rectangle can be moved anywhere with your mouse.
Series Chart Stacked Example

Merged curves

Curves are drawn one over another on the same layer.

Note
When curves are drawn on the same layer, a rectangle with captions appears on the chart. This rectangle can be moved anywhere with your mouse.
Series Chart Merged Example

Standalone curves with tabs

Curves are drawn on separate layers. You can click on the tabs to switch from one layer to another.

Series Chart Standalone Example

Standalone curves in scrollable pages

Curves are drawn on separate layers. You can click and move the mouse on the left or the right over the dots (like Android pages on smartphones) to switch from one layer to another.

Series Chart Standalone Scrolling Example


Renderer Definition File

[image]

MADCAT User Guide
Renderer Definition File
Send Feedback
MADCAT User Guide v1.2.2

The definition file is a XML file which comes along with the library (DLL). Its extension is XRD. It is read by MADCAT during start-up. It contains important elements :

  • Name, icon and description of the renderer
  • Path of the DLL
  • List of the supported modes with their names, icons and descriptions

These information are used by MADCAT to display renderer's buttons into explorer windows of the user interface.


Rendering Modes

[image]

MADCAT User Guide
Rendering Modes
Send Feedback
MADCAT User Guide v1.2.2

Each renderer can implement one or more rendering modes. Modes change the style of the display. End-user can change the mode by clicking on the drop-down button of the renderer in the explorer tool bar. The modes are defined in the renderer definition file (XRD).

Special features

Renderers can also integrate new buttons in the explorer tool bar to add new features or control the display.

User options

Renderers can also define a set of parameters which can be changed by the end-user in the "Options" form of MADCAT. These parameters can control the behaviour of the renderer.

Interaction with models

Workspace suppliers can also define rendering options in their models. ITEM and FOLDERS has specific attributes to control the renderers. With these attributes, you can automatically switch to a specific renderer and a mode when the end-user "opens" an element in an explorer window.


Reports

[image]

MADCAT User Guide
Reports
Send Feedback
MADCAT User Guide v1.2.2

Reports are used to convert XML data of the end-user's project into HTML. The conversion is done with this procedure :

  • 1 - End-user runs the report by double-clicking on its icon in the Report window of the application.
  • 2 - The report selects some items using a given XPath expression. If this expression needs end-user's inputs, a dialog box opens and waits for the user entries.
  • 3 - MADCAT runs .Net framework XSLT Transformation using a given style sheet

MADCAT generates the preview into a folder named "Output". If this folder doesn't exist in your workspace, you will see a warning message and the preview will be generated in the TEMP directory of your system. If your style sheet refers to external files like HTML style sheets (.CSS) or Javascript (.JS), the use of the TEMP directory may produce unexpected results during the conversion. Using the "Output" directory, you can place all these files at the right place before the genaration to have a good result immediatly. In any case, if the preview is not correct, you will be able to save the HTML output anywhere in your system and open it with your prefered browser. The XPath expression, the required parameters and the style sheet are provided by the Report definition file (XPT file). The XPT file is a simple XML file which must be located in the "Reports" folder of your workspace. The XML file shall be compliant with the following schema :

Report definition file (XPT)

Report is a XML file which defines a standard XPATH query to execute on the databases of a workspace and a XML stylesheet (XSLT) for formatting. Extension is XPT. The ouput can be HTML or XML. End-user can save it into a file.

This report has been generated by MADCAT using this definition :

CopyXML
<?xml version="1.0"?>
<REPORT NAME='List of workspaces' xmlns="http://www.themadcat.fr/reports">
    <QUERY>//WORKSPACE</QUERY>
    <STYLESHEET>Styles/wrkspc_list.xsl</STYLESHEET>
</REPORT>

Reports panel

MADCAT loads report files on start-up. End-user can produce reports from MADCAT's user interface.

Using parameters in reports

Reports can use input parameters to control the content of the report : the values of the parameters are used in the XPath expression. For example, the Report definition defines one parameter :

CopyXML
<?xml version="1.0"?>
<REPORT NAME='Usage of a renderer' xmlns="http://www.themadcat.fr/reports">
    <QUERY>//WORKSPACE[RENDERERS/RENDERER[@NAME='%%RENDERERNAME%%']]</QUERY>
    <STYLESHEET>Styles/wrkspc_list_renderer.xsl</STYLESHEET>
    <PARAMETER NAME='RENDERERNAME' DESC='Renderer name' TYPE='STR' OPTIONS='mandatory=yes'/>
</REPORT>

Note that the XPath expression refers to the parameter name with the delimiters %% When users runs the report, a form opens to request the parameter value :

The report is generated if user enters mandatory values and click on "Generate"

report sample param

The XSL used for this example is below :

CopyXML
<xsl:stylesheet version="1.0">
    <xsl:output method="html"/>
    <xsl:template match="/">
        <html>
            <head>
                <title>List of your workspaces</title>
            </head>
            <body>
                <h1>List of your workspaces using renderer <xsl:value-of select="//RENDERER/@NAME"/></h1>
                <table cols="3" border="1">
                    <tr>
                        <th width="200">Name</th><th width="600">Description</th><th width="600">Last generation path</th>
                    </tr>
                    <xsl:apply-templates/>
                </table>
            </body>
        </html>
    </xsl:template>
    <xsl:template match="WORKSPACE">
        <tr>
            <td><xsl:value-of select="@NAME"/></td><td><xsl:value-of select="@DESCRIPTION"/></td><td><xsl:value-of select="@LASTGENERATION"/></td>
        </tr>
    </xsl:template>
</xsl:stylesheet>


Workspace creation

[image]

MADCAT User Guide
Workspace creation
Send Feedback
MADCAT User Guide v1.2.2

Workspace is the name used to identify the group of MADCAT elements that constitute your application. It is always composed of a set of models and may be completed by tools, renderers and reports. Basically, all these elements should be stored in specific sub folders of one folder. This root folder is the physical location of your workspace. It owns the workspace definition file and the following sub folders :

  • Models (location of your models definition files)
  • Tools (location of your tool definition files and DLL)
  • Renderers (location of your renderer definition files and DLL)
  • Types (location of your type handlers (DLL))
  • Reports (location) of your report definition files
  • Project (location of your databases build using the models). If baseline management is active, it may contain many sub folders (one per baseline) and baseline event files.

Additional folders may be added in order to have a "clean" organization :

  • Bitmaps (location of the icons, bitmaps, referenced by the models, tools, renderers definition files)
  • Styles (location of HTML style sheet, XSLT files, ... used to format data in reports)
  • Output (location of report previews)

The names listed above are the one used by default by MADCAT. If you use these names, MADCAT can recognize the workspace and activate it without using any workspace definition file.

The workspace definition file is the "startup" file : the one which can be loaded by MADCAT to start your application. It contains the name of your application, the name of the author of the application, a reference to a help file, a short description, a splashscreen configuration and some display options (background picture, application icon). It also defines the current baseline (baseline management is deactivated if the baseline is not defined) if user wants to use baselines.

But it can also contain the locations of each elements (models, reports, tools, renderers and types) if your workspace physical structure is not the one described above.

This feature enables the sharing of MADCAT elements between workspaces. This is a key point which will greatly improve the reusability of your models, tools, renderers and types among one or more workspaces !

Obviously, such capability is possible only when tools, renderers and types are designed for very specific tasks. You should avoid the "swiss knife" designs. If you want to develop an application which has multiple functions, handles multiple kind of items, etc... I greatly advise you to clearly segregate the functions into different tools, different items and different renderers. The more tools, renderers and models are simple and dedicated to one function, the more you'll be able to combine them to make new workspaces.

For example, you can build an application which can manage pictures, videos, texts, organize them, classify them, and so on... If you build one tool for each kind of task, a model for each kind of item (one for videos, one for pictures, ...) and a renderer for each item too, you'll be able to make simple associations between model-tool-renderer and finally distribute new applications which have only a subset of the first one :

For example, one application to manage pictures, one application to manage texts or one application to only picture and videos.

At the end, even your users will be able to compose their own application very easily : grab only the tools, renderers and models they use and make a new workspace which exactly fit their needs by combining them. This is the end of very complicated "swiss-knife" applications with endless menus, options, ...

The workspace editor is the application which can help you manage your MADCAT elements, combine them and build workspaces. Note that MADCAT can switch very quickly from one workspace to another. It is not useful to put all your tools into the same workspace. Make several workspaces and switch from one to another in accordance with the task you're planning to do !


Workspace Editor

[image]

MADCAT User Guide
Workspace Editor
Send Feedback
MADCAT User Guide v1.2.2

This topic contains the following sections.

  • The databases
  • The tool

The Workspace Editor is a MADCAT workspace designed to help you create and manage your own workspaces. This section will explain to you how to use it.

The databases

The workspace editor has 5 databases :

  • One for the tools definitions

  • One for the renderers definitions

  • One for the reports definitions

  • One for the models

  • And one for the workspaces definitions

Data Sources Bar

Data is organized such as tools, renderers, reports and models can be defined once and used multiple times in different workspaces definitions.

So the best way to process is to define your sets of tools, renderers and reports. Then build your models (they will refer to tools and renderers) and finally setup your workspaces (which will refer to all the other elements).

All the databases are described in the sub-chapter of this help file.

The very last step is the generation of the workspace itself on your file system. To do this, a dedicated tool is included in the Workspace Editor.

The tool

The workspace editor has one tool which will generate all the definition files on your system.

Just select the workspace you want in the database "My workspaces"

Workspace Editor Workspace Select

then click on the button "Generate".

Workspace Editor Generate Button

The wizard will appear on your screen, asking you to select a destination path :

Workspace Editor Generate Step 1

then specify if you want to switch to this new workspace right after the generation process to check it in live :

Workspace Editor Generate Step 2

Right after this step, the process starts. If the destination folder is not empty, a confirmation is required to continue :

Workspace Editor Generate Warning

Click on "Ok" to continue or "Cancel" to cancel the operation.

A detailed log is generated during the generation process.

Workspace Editor Generate Log
Note
The log is available even if you switch to the new workspace because messages are always kept in memory until the MADCAT is closed. So just create a logbook or open a logbook with no filters on, then fill it with all the messages.


My tools
Send Feedback
MADCAT User Guide v1.2.2

This section shows how tools are organized in the Workspace Editor

My Tools

This database is structured as follow :

Workspace Editor Tool Elements

Tools have the following attributes :

Workspace Editor Tool Attributes

Actions are created in the folder "Actions performed by the tool" and have the following attributes :

Workspace Editor Action Attributes


My renderers
Send Feedback
MADCAT User Guide v1.2.2

This section shows how renderers are organized in the Workspace Editor

My Renderers

This database is structured as follow :

Workspace Editor Renderer Elements

Renderers have the following attributes :

Workspace Editor Renderer Attributes

Modes are created in the folder "Modes offered by the renderer" and have the following attributes :

Workspace Editor Mode Attributes


My reports
Send Feedback
MADCAT User Guide v1.2.2

This section shows how reports are organized in the Workspace Editor

My Reports

This database is structured as follow :

Workspace Editor Report Elements

Reports have the following attributes :

Workspace Editor Report Attributes

Parameters are created in the folder "Query Parameters" and have the following attributes :

Workspace Editor Report Param Attributes


My models
Send Feedback
MADCAT User Guide v1.2.2

This section shows how models are organized in the Workspace Editor

This topic contains the following sections.

  • My Models
  • the Items
  • the Series
  • the Folders
  • the Links
  • the Queries
  • the Multiview configurations

My Models

This database is structured as follow :

Workspace Editor Model Elements

Models have the following attributes :

Workspace Editor Model Attributes

the Items

Items are created in the folder "Allowed child elements" and have the following attributes :

Workspace Editor Item Attributes

Items have attributes which are defined in the folder "Attributes". They have the specific attributes and can be created using this context menu :

Workspace Editor Add Attribute Menu

the Series

Series are created in the folder "Allowed child elements" and have the following attributes :

Workspace Editor Series Attributes

Series have attributes which are defined in the folder "Attributes". They have the specific attributes and can be created using this context menu :

Workspace Editor Add Attribute Menu

the Folders

Folders are created in the folder "Allowed child elements" and have the following attributes :

Workspace Editor Folder Attributes

the Links

Links are created in the folder "Allowed child elements" and have the following attributes :

Workspace Editor Link Attributes

the Queries

Queries are created in the folder "Allowed child elements" and have the following attributes :

Workspace Editor Query Attributes

the Multiview configurations

Items, Folders and Series also have multiview configurations which are defined in the folder "Multiview configurations" of the model. Multiview configurations have View sub-elements which have these attributes :

Workspace Editor View Attributes


My workspaces
Send Feedback
MADCAT User Guide v1.2.2

This section shows how workspaces are organized in the Workspace Editor

My Workspaces

This database is structured as follow :

Workspace Editor Workspace Elements

Renderers have the following attributes :

Workspace Editor Workspace Attributes 1
Workspace Editor Workspace Attributes 2

Elements (tools, renderers, reports, models) are associated to the workspace by creating links in the folders of the workspace element.


Xml Files Reference

[image]

MADCAT User Guide
Xml Files Reference
Send Feedback
MADCAT User Guide v1.2.2

This section contains the definitions of the Xml files used by MADCAT (the files presented in the section Workspace description). The schemas presented here are the ones stored in the MADCAT installation directory.

Important
You shall never modify the XSD files installed with MADCAT.
Important

ALL THE DEFINITIONS FILES SHALL INDICATE THE XML NAMESPACE IN THEIR ROOT ELEMENT. YOU MAY HAVE UNPREDICTABLE BEHAVIORS IF IT IS MISSING.

File | Extension | Namespace
Workspace Definition File | XWS | http://www.themadcat.fr/workspaces
Tool Definition File | XTL | http://www.themadcat.fr/tools
Renderer Definition File | XRD | http://www.themadcat.fr/renderers
Model Definition File | XML | http://www.themadcat.fr/models
Report Definition File | XPT | http://www.themadcat.fr/reports


Workspace definition schema

[image]

MADCAT User Guide
Workspace definition schema
Send Feedback
MADCAT User Guide v1.2.2

Workspace definition file is described in detail in the section Workspace Description

The root element

A workspace definition shall begin with the following XML information :

CopyXML
<?xml version="1.0" encoding="UTF-8"?>

then the root element shall be :

CopyXML
<WORKSPACE NAME='<Name of the workspace>' xmlns="http://www.themadcat.fr/workspaces">

Attributes and Elements

Attributes

Name | Type | Class | Description
NAME | String | Mandatory | Name of the workspace (Title of the main window)
LOCK | String | Optional | Set this attribute to YES to lock the workspace definition. Users won't be able to add or remove any elements (Models, Tools or Renderers).

Child Elements

Name | Multiplicity | Definition
IDENTIFIER | Unique and Mandatory | Element contains the ID of the workspace. Used to identify the workspace in your system. This name should be unique in the whole system.
MODELSSELECTION | Multiple and Mandatory(*) | Go to MODELSSELECTION definition
PROJECTPATH | Multiple and Mandatory(*) | Go to PROJECTPATH definition
REFERENCEDBY | Unique (Optional) | Reserved by the MADCAT
DESCRIPTION | Unique (Optional) | Element contains a text which describes the workspace's objectives
ICON | Unique (Optional) | Element contains a path (absolute or relative to the workspace's location) of a bitmap file used as an icon for the main window
AUTHOR | Unique (Optional) | Element contains the name of the author of the workspace
BASELINE | Unique (Optional) | Element contains the name of the baseline to load when the workspace starts
HELPFILE | Unique (Optional) | Element contains a path (absolute or relative to the workspace's location) of a help file called with the Help menu of the main window
BACKGROUNDIMAGE | Unique (Optional) | Go to BACKGROUNDIMAGE definition
SPLASHSCREEN | Unique (Optional) | Go to SPLASHSCREEN definition
TYPESPATH | Multiple (Optional) | Element contains a path (absolute or relative to the workspace's location) to DLLs of external types
TOOLSSELECTION | Multiple (Optional) | Go to TOOLSSELECTION definition
RENDERERSSELECTION | Multiple (Optional) | Go to RENDERERSSELECTION definition
MODELSPATH | Multiple (Optional and deprecated) | Element contains a path (absolute or relative to the workspace's location) to Xml definitions of your data
REPORTSPATH | Multiple (Optional and deprecated) | Element contains a path (absolute or relative to the workspace's location) to DLLs of external types
TOOLSPATH | Multiple (Optional and deprecated) | Element contains a path (absolute or relative to the workspace's location) to DLLs of external types
RENDERERSPATH | Multiple (Optional and deprecated) | Element contains a path (absolute or relative to the workspace's location) to DLLs of external types
Note
(*) : The XWS file shall contain at least one MODELSSELECTION element and one PROJECTPATH element

Parent Elements

None


Definition for element "BACKGROUNDIMAGE"

[image]

MADCAT User Guide
Definition for element "BACKGROUNDIMAGE"
Send Feedback
MADCAT User Guide v1.2.2

Defines the bitmap file which will be used as the background image of the main form.

Attributes and Elements

Attributes

Name

Type

Class

Description

LAYOUT

Enumerate

Optional

One of the following values :

  • center

  • stretch

  • tile

  • zoom

  • none

Child Elements

None. The element contains a path (absolute or relative to the workspace's location) to a bitmap file which will be used as the background image of the main form.

Parent Elements

Name | Multiplicity | Definition
WORKSPACE | Unique | Go to WORKSPACE definition


Definition for element "SPLASHSCREEN"

[image]

MADCAT User Guide
Definition for element "SPLASHSCREEN"
Send Feedback
MADCAT User Guide v1.2.2

Defines the bitmap file which will be used as the startup screen of your workspace.

Attributes and Elements

Attributes

Name | Type | Class | Description
DURATION | String | Optional | Timeout in seconds for the splashscreen. If the user doesn't click on it before the timeout the splashscreen disappears automatically.

Child Elements

None. The element contains a path (absolute or relative to the workspace's location) to a bitmap file which will be used as the startup screen of the workspace.

Parent Elements

Name | Multiplicity | Definition
WORKSPACE | Unique | Go to WORKSPACE definition


Definition for element "TOOLSSELECTION"

[image]

MADCAT User Guide
Definition for element "TOOLSSELECTION"
Send Feedback
MADCAT User Guide v1.2.2

Defines the tools to load when the workspace starts.

Attributes and Elements

Attributes

Name

Type

Class

Description

PATH

String

Mandatory

Path (relative to the value of WORKSPACEPATH) where the tools are selected.

WORKSPACEPATH

String

Mandatory

Path of the workspace where the tools are.

RULE

Enumerate

Mandatory

Selection rule (one of the following values) :

  • AddAllThenIgnore

  • IgnoreAllThenAdd

Child Elements

Name | Multiplicity | Definition
ADD | Multiple (if rule if IgnoreAllThenAdd) | Filename of the tool definition (.xtl) to add in the selection
IGNORE | Multiple (if rule if AddAllThenIgnore) | Filename of the tool definition (.xtl) to exclude in the selection

Parent Elements

Name | Multiplicity | Definition
WORKSPACE | Unique | Go to WORKSPACE definition


Definition for element "MODELSSELECTION"

[image]

MADCAT User Guide
Definition for element "MODELSSELECTION"
Send Feedback
MADCAT User Guide v1.2.2

Defines the models to load when the workspace starts.

Attributes and Elements

Attributes

Name

Type

Class

Description

PATH

String

Mandatory

Path (relative to the value of WORKSPACEPATH) where the models are selected.

WORKSPACEPATH

String

Mandatory

Path of the workspace where the models are.

RULE

Enumerate

Mandatory

Selection rule (one of the following values) :

  • AddAllThenIgnore

  • IgnoreAllThenAdd

Child Elements

Name | Multiplicity | Definition
ADD | Multiple (if rule if IgnoreAllThenAdd) | Filename of the model definition (.xml) to add in the selection
IGNORE | Multiple (if rule if AddAllThenIgnore) | Filename of the model definition (.xml) to exclude in the selection

Parent Elements

Name | Multiplicity | Definition
WORKSPACE | Unique | Go to WORKSPACE definition


Definition for element "RENDERERSSELECTION"

[image]

MADCAT User Guide
Definition for element "RENDERERSSELECTION"
Send Feedback
MADCAT User Guide v1.2.2

Defines the renderers to load when the workspace starts.

Attributes and Elements

Attributes

Name

Type

Class

Description

PATH

String

Mandatory

Path (relative to the value of WORKSPACEPATH) where the renderers are selected.

WORKSPACEPATH

String

Mandatory

Path of the workspace where the renderers are.

RULE

Enumerate

Mandatory

Selection rule (one of the following values) :

  • AddAllThenIgnore

  • IgnoreAllThenAdd

Child Elements

Name | Multiplicity | Definition
ADD | Multiple (if rule if IgnoreAllThenAdd) | Filename of the renderer definition (.xrd) to add in the selection
IGNORE | Multiple (if rule if AddAllThenIgnore) | Filename of the renderer definition (.xrd) to exclude in the selection

Parent Elements

Name | Multiplicity | Definition
WORKSPACE | Unique | Go to WORKSPACE definition


Definition for element "PROJECTPATH"

[image]

MADCAT User Guide
Definition for element "PROJECTPATH"
Send Feedback
MADCAT User Guide v1.2.2

Defines the location of the data files (Xml files) of your project.

Attributes and Elements

Attributes

Name | Type | Class | Description
BASELINE | String | Optional | Name of the baseline to load

Child Elements

None. The element contains a path (absolute or relative to the workspace's location) to the Xml files of your project.

Parent Elements

Name | Multiplicity | Definition
WORKSPACE | Unique | Go to WORKSPACE definition


Models schema

[image]

MADCAT User Guide
Models schema
Send Feedback
MADCAT User Guide v1.2.2

Models are the main part of your workspace. They define the items the end-user can create/manipulate and the actions it can perform on them. The content of a model can be simple or complicated. Many Xml elements are available to model your database. One thing to remember is that one model while produce one (and only one) database.

A workspace can have one or more models. Models can refer to each other by the use of links. So a model in an XML file which shall be compliant with the following schema. The XML file shall be located in the "Models" folder of your workspace (see workspace.txt)

Model schema

The root element

A model shall begin with the following XML information :

CopyXML
<?xml version="1.0" encoding="UTF-8"?>

then the root element shall be :

CopyXML
<DATAMODEL NAME='<Name of the database>' TITLE='<Title of the database>' xmlns="http://www.themadcat.fr/models">

Attributes and Elements

Attributes and elements

Attributes

Name | Type | Class | Description
NAME | String | Mandatory | Name of the database. This name is used to refer to the database in other models, tools, renderers, etc... (for development only. End-user don't care about this name)
TITLE | String | Mandatory | Title of the database. This title is used for the end-user interface. This is the name the end-user will see and know.
ICON | Filename | Optional | Bitmap file which contains the icon of the database.
COLOR | HTML color code | Optional | Color code of the database. The MADCAT explorer window will use this color to display item's path. Can be useful to distinguish quickly a database from another when multiple explorer windows are opened.

Child Elements

Name | Multiplicity | Definition
ITEM | Multiple | Go to ITEM definition
FOLDER | Multiple | Go to FOLDER definition
LINK | Multiple | Go to LINK definition
QUERY | Multiple | Go to QUERY definition

Parent Elements

None


Definition for element "ITEM"

[image]

MADCAT User Guide
Definition for element "ITEM"
Send Feedback
MADCAT User Guide v1.2.2

Element used to define an item of a database. Items are entities which can be created/edited/deleted/selected by the end-user and actions can be performed on them.

Attributes and Elements

Attributes

Name | Type | Class | Description
NAME | String | Mandatory | Name of the item. Used to identify the item in the database. This name should be unique in the whole workspace the model is for. End-user will use this name to refer to the item.
NODENAME | String | Mandatory | Name of the XML element which will be used to store the item data in the database. Used by the end-user in his XPath expressions.
ICON | Filename | Optional | Bitmap file which contains the icon of the item. For dynamic icons, use '@' followed by the name of an attribute of the item. It is recommended to use a bitmap attribute as source. See Control item's icon for more details.
STYLESHEET | Filename | Optional | XSL file which should be used to generate the HTML output when the item is printed by the end-user. If empty, the end-user will only print XML data.
RENDERER | String | Optional | Name of the renderer to activate when the item's children are displayed in a MADCAT explorer window. If this attribute is set, MADCAT explorer window will activate the renderer (if it is available) when the end-user opens the item (this feature works only with items having children).
RENDERMODE | String | Optional | Name of the mode to activate. Used only if the attribute RENDERER is set and renderer exists. MADCAT will activate the mode when activating the renderer.
RENDEROPTIONS | String | Optional | List of options to pass to the renderer when activating the mode defined by RENDERMODE. Used only if the attributes RENDERER and RENDERMODE are set. The list of options depends on the renderer (proprietary format) but generally it is a sequence of couple 'option=value' separated by comas.
REFERSTO | String | Optional | Name of another ITEM element within the same model. If set, the item element will automatically inherit all the attributes and children of the given ITEM element. Used to create several items in one model having the same properties without the need of repeating the definition each time.

Child Elements

Name | Multiplicity | Definition
ITEM | Multiple | Go to ITEM definition
SERIES | Multiple | Go to SERIES definition
FOLDER | Multiple | Go to FOLDER definition
LINK | Multiple | Go to LINK definition
QUERY | Multiple | Go to QUERY definition
ACTION | Multiple | Go to ACTION definition
TRIGGER | Multiple | Go to TRIGGER definition
ATTRIBUTE | Multiple | Go to ATTRIBUTE definition
INHERITS | Multiple | Go to INHERITS definition
MULTIVIEW | Unique | Go to MULTIVIEW definition

Parent Elements

Name | Definition
ITEM | Go to ITEM definition
FOLDER | Go to FOLDER definition
SERIES | Go to SERIES definition
DATAMODEL | Go to DATAMODEL definition


Definition for element "ATTRIBUTE"

[image]

MADCAT User Guide
Definition for element "ATTRIBUTE"
Send Feedback
MADCAT User Guide v1.2.2

Element used to define an attribute of an item. Attributes are atomic pieces of data. They store one unique value of a given type. An item can have several attributes.

Attributes and Elements

Attributes

Name | Type | Class | Description
NAME | String | Mandatory | Name of the attribute. Must be unique for the item. It is used to build the XML element in the database defined by the model. Used by the end-user in his XPath expressions.
DESC | String | Mandatory | Description of the attribute. Displayed in the explorer window's columns (in detailed view mode), in the edit forms, etc...
TYPE | String | Mandatory | Type of the attribute. Must be one of the following value : STR (String or Text), NUM (Numeric), BMP (Bitmap file), FILE (File), DIR (Directory), IPADDR (IP Address), ENUM (Enumerate), GRP (Group of attributes), BOOL (Boolean), DATETIME (Date and time), COLOR (Color). It can also be the name of type handled by a specific library in the "Types" folder of the workspace. In this case, the name of the type shall be the name of the DLL which handles the type. The DLL shall be in the "Types" folder of the workspace.
HELP | String | Optional | Help information displayed as a tip in MADCAT's forms (when end-user moves its mouse over the name of the attribute for example).
OPTIONS | String | Optional | List of options used to control the appearance and the behaviour of the attribute in MADCAT's interface. The list of options depends on the type of the attribute. See the ParameterDemo workspace for a detailed list of options. The most important options are : 'mandatory'. When it is set to 'yes', the attribute is mandatory and must be filled in order to add an item in the database. 'readonly'. When it is set to 'yes', the end-user can't modify the attribute value. It is useful for attributes filled by tools only. These 2 attributes are available on any types.
DEFAULT_VALUE | String | Optional | Default value of the attribute when a new item is initialized before end-user completes it and adds it to the database.

Child Elements

Name | Multiplicity | Definition
ENUM | Multiple | Go to ENUM definition

Parent Elements

Name | Definition
ITEM | Go to ITEM definition


Samples of attributes

[image]

MADCAT User Guide
Samples of attributes
Send Feedback
MADCAT User Guide v1.2.2

Here are some samples of all the options available for each type of attribute.

Strings (STR)

options for str

Numbers (NUM)

options for num
options for num 2
options for num 3
options for num 4

Bitmaps (BMP)

options for bmp
options for bmp 2
options for bmp 3
options for bmp 4

Files (FILE)

options for file
options for file 1
options for file 2
options for file 3

Directories (DIR)

options for dir
options for dir 2
options for dir 3

Enumerations (ENUM)

options for enum

Booleans (BOOL)

options for bool

Colors (COLOR)

options for color

IP Addresses (IPADDR)

options for ipaddr

Dates and times (DATETIME)

options for datetime


Definition for element "ENUM"

[image]

MADCAT User Guide
Definition for element "ENUM"
Send Feedback
MADCAT User Guide v1.2.2

Attributes and Elements

Attributes

Name | Type | Class | Description
VALUE | String | Mandatory | One possible value of the attribute. Must be unique for the attribute. This information will be directly stored in the XML database.
LABEL | String | Optional | Label attached to the value. Used to display a clear information when the value is not "human-readable". This information is not stored in the database but used only for display purpose.

Child Elements

None

Parent Elements

Name | Definition
ATTRIBUTE | Go to ATTRIBUTE definition for MODELS
ATTRIBUTE | Go to ATTRIBUTE definition for REPORTS


Definition for element "ACTION"

[image]

MADCAT User Guide
Definition for element "ACTION"
Send Feedback
MADCAT User Guide v1.2.2

Element used to bind an action to an item or a folder. Actions are treatments performed by a tool on one or several items (or folders). When the end-user selects an item which has ACTION elements in the model, MADCAT activates the buttons of the tool bar which are attached to the actions defined by these elements (it activates also the action in the contextual menu of the item). The action is not run automatically but the end-user can run it by pressing the button.

Attributes and Elements

Attributes

Name | Type | Class | Description
NAME | String | Mandatory | Name of the action. Must be a name defined in a tool definition file (XTL file) of your workspace.
DESC | String | Optional | Description of the action which can be performed on the item.

Child Elements

None

Parent Elements

Name | Definition
ITEM | Go to ITEM definition
FOLDER | Go to FOLDER definition


Definition for element "TRIGGER"

[image]

MADCAT User Guide
Definition for element "TRIGGER"
Send Feedback
MADCAT User Guide v1.2.2

Element used to bind an action to an item or a folder and a specific user event. Actions are treatments performed by a tool on one or several items (or folders). When the end-user executes the expected event of a trigger on the item (or folder), MADCAT runs the action attached to the trigger. The end-user can't control this execution but it can activate/deactivate triggers of a database by using the configuration panel of MADCAT.

Attributes and Elements

Attributes

Name

Type

Class

Description

NAME | String | Mandatory | Name of the trigger.
DESC | String | Mandatory | Description of the action which can be performed on the item when event is triggered. This description is displayed in the configuration panel of MADCAT.
EVENT String Mandatory Event which will activate the trigger. Must be one of the following value:

  • BEFEDIT

  • AFTEDIT

  • BEFLINK

  • AFTLINK

  • BEFCREATE

  • AFTCREATE

  • BEFDEL

  • SELECT

  • ACTIVATE

  • DROP

  • TIMER

ACTION | String | Mandatory | Name of the action to run. Must be a name defined in a tool definition file (XTL file) of your workspace.
NODENAME | String | Mandatory if EVENT=DROP | Name of the item which shall be dropped on the item (or folder) to activate the trigger
DATAMODEL | String | Mandatory if EVENT=DROP | Name of the database which owns the items which shall be dropped on the item (or folder) to activate the trigger
TIMERPERIOD | Non-negative Integer | Mandatory if EVENT=TIMER | Period of the activation of the action expressed in milliseconds. Must be greater or equal to 10ms.

Child Elements

None

Parent Elements

Name | Definition
ITEM | Go to ITEM definition
FOLDER | Go to FOLDER definition
SERIES | Go to SERIES definition


Definition for element "INHERITS"

[image]

MADCAT User Guide
Definition for element "INHERITS"
Send Feedback
MADCAT User Guide v1.2.2

Inheritance is the mechanism which allows you to create new definitions from an existing one. You can add new attributes, actions, triggers, children elements to an existing definition and give it a new name. It works like class inheritance in Java or C++ programming language.

The new definition can also override its parent definition. In this case, the parent definition won't be activated in the workspace; it will be replaced by the child definition.

Attributes and Elements

Attributes

Name | Type | Class | Description
NODENAME | String | Mandatory | Name of the XML element which can be refered to by the link. Can be the name of any item of any models within the same workspace.
DATAMODEL | String | Mandatory | Name of the database which owns the item defined in the attribute NODENAME. Can be any database of the workspace.
OVERRIDE | String | Optional | Set this attribute to 'YES' if the current definition overrides its parent.

Child Elements

None

Parent Elements

Name | Definition
ITEM | Go to ITEM definition
FOLDER | Go to FOLDER definition
SERIES | Go to SERIES definition


Definition for element "MULTIVIEW"

[image]

MADCAT User Guide
Definition for element "MULTIVIEW"
Send Feedback
MADCAT User Guide v1.2.2

Element used to configure the explorer window when multiview mode is activated by the user.

Every item, series or folder having this element will change the window configuration when it is selected by the end-user. The explorer window will create panels for each VIEW element defined in this element

Attributes and Elements

Attributes

None

Child Elements

Name | Multiplicity | Definition
VIEW | Multiple | Go to VIEW definition

Parent Elements

Name | Definition
ITEM | Go to ITEM definition
FOLDER | Go to FOLDER definition
SERIES | Go to SERIES definition


Definition for element "VIEW"

[image]

MADCAT User Guide
Definition for element "VIEW"
Send Feedback
MADCAT User Guide v1.2.2

Element used to define an view of a multiview configuration. Views create dockable forms in the explorer window when the multiview mode is activated.

Use views to display complex items (attributes and children) with different renderers.

Attributes and Elements

Attributes

Name | Type | Class | Description
TITLE | String | Mandatory | Title of the view. Will be placed in the title bar of the dock form
RENDERER | String | Mandatory | Name of the renderer to activate in the dock form.
POSITION | String | Mandatory | Position of the form in the explorer window. Must be one of following values : top, bottom, left, right, fill, center
CONTENT | String | Mandatory | Node name of the items, series or folder to display in the form. Leave blank to see all the elements in the form.
RENDERMODE | String | Optional | Name of the mode to activate. Used only if the attribute RENDERER is set and renderer exists. MADCAT will activate the mode when activating the renderer.
RENDEROPTIONS | String | Optional | List of options to pass to the renderer when activating the mode defined by RENDERMODE. Used only if the attributes RENDERER and RENDERMODE are set. The list of options depends on the renderer (proprietary format) but generally it is a sequence of couple 'option=value' separated by comas.
AUTOHIDE | Boolean | Optional | Activate or deactivate the auto-hide feature of the form. When set, the form will be hidden in the border of the explorer window when the mouse cursor leaves the form.
WIDTH | Non negative integer | Optional | Width of the form in pixels.
HEIGHT | Non negative integer | Optional | Height of the form in pixels.

Child Elements

None

Parent Elements

Name | Definition
MULTIVIEW | Go to MULTIVIEW definition


Definition for element "LINK"

[image]

MADCAT User Guide
Definition for element "LINK"
Send Feedback
MADCAT User Guide v1.2.2

Element used to define a link to one item of a database. Links are entities which can be created/deleted/selected by the end-user and actions can be performed on them. They are shortcuts (or references) to other items created by the end-user in the database. Defining a LINK in a model just activate the possibility for the end-user to create links to specific items in one item or one folder. This will avoid the classic copy of the item. Data is never duplicated. When the end-user prints a link or an item or a folder which has links inside, MADCAT resolves links and automatically replace the link by the item it refers to. Using the same principle, when a tool performs an action on an item or a folder which has links inside, MADCAT resolves the links and the tools will directly "see" the XML data of the target item instead of the link itself. Their can be seen as phantom items as their data is never seen by the end-user or tools. Their content is dynamically replaced by the data of the target item (like if the target were actually a child of the printed item for example) when needed.

Attributes and Elements

Attributes

Name | Type | Class | Description
NAME | String | Mandatory | Name of the link. Used to identify the link in the database. This name should be unique in the whole workspace the model is for. End-user will never see this information. Used only to store link data into the XML database.
NODENAME | String | Mandatory | Name of the XML element which can be refered to by the link. Can be the name of any item of any models within the same workspace.
DATAMODEL | String | Mandatory | Name of the database which owns the item defined in the attribute NODENAME. Can be any database of the workspace.

Child Elements

None

Parent Elements

Name | Definition
ITEM | Go to ITEM definition
FOLDER | Go to FOLDER definition
DATAMODEL | Go to DATAMODEL definition


Definition for element "FOLDER"

[image]

MADCAT User Guide
Definition for element "FOLDER"
Send Feedback
MADCAT User Guide v1.2.2

Element used to define a folder of a database. Folders are entities which can't be created/edited/deleted by the end-user. They are built and managed automatically by MADCAT. If an ITEM has one folder, the folder will be created when the ITEM is created by the end-user.

Attributes and Elements

Attributes

Name | Type | Class | Description
NAME | String | Mandatory | Name of the folder. Used to identify the folder in the database. End-user will use this name to refer to the folder.
NODENAME | String | Mandatory | Name of the XML element which will be used to store the folder data in the database.
ICON | Filename | Optional | Bitmap file which contains the icon of the folder when closed.
ICON_OPEN | Filename | Optional | Bitmap file which contains the icon of the folder when opened. If empty, the icon defined by the attribute ICON is used.
STYLESHEET | Filename | Optional | XSL file which should be used to generate the HTML output when the folder and its content are printed by the end-user. If empty, the end-user will only print XML data.
RENDERER | String | Optional | Name of the renderer to activate when the folder's children are displayed in a MADCAT explorer window. If this attribute is set, MADCAT explorer window will activate the renderer (if it is available) when the end-user opens the folder (this feature works only with folders having children).
RENDERMODE | String | Optional | Name of the mode to activate. Used only if the attribute RENDERER is set and renderer exists. MADCAT will activate the mode when activating the renderer.
RENDEROPTIONS | String | Optional | List of options to pass to the renderer when activating the mode defined by RENDERMODE. Used only if the attributes RENDERER and RENDERMODE are set. The list of options depends on the renderer (proprietary format) but generally it is a sequence of couple 'option=value' separated by comas.

Child Elements

Name | Multiplicity | Definition
ITEM | Multiple | Go to ITEM definition
SERIES | Multiple | Go to SERIES definition
FOLDER | Multiple | Go to FOLDER definition
LINK | Multiple | Go to LINK definition
QUERY | Multiple | Go to QUERY definition
ACTION | Multiple | Go to ACTION definition
TRIGGER | Multiple | Go to TRIGGER definition
INHERITS | Multiple | Go to INHERITS definition
MULTIVIEW | Unique | Go to MULTIVIEW definition

Parent Elements

Name | Definition
ITEM | Go to ITEM definition
FOLDER | Go to FOLDER definition
DATAMODEL | Go to DATAMODEL definition


Definition for element "QUERY"

[image]

MADCAT User Guide
Definition for element "QUERY"
Send Feedback
MADCAT User Guide v1.2.2

Element used to define a dynamic query. Queries are used to dynamically execute a XML query (using XPath expressions) and display the result in a MADCAT Explorer window. A query will never produce any data in the database. This is only used for dynamic display on screen. They behave like folders with dynamic content. For example, you can use queries to list important items (faulty items, hot items, etc...) to the end-user in a specific folder of your database. The end-user can't change the content of a query result but he can edit items displayed inside.

Attributes and Elements

Attributes

Name | Type | Class | Description
NAME | String | Mandatory | Name of the query. Used to identify the query in the interface of MADCAT. End-user will use this name to refer to the query.
XPATH | String | Mandatory | XPath expression which will be performed by MADCAT on the database of the model when the end-users opens the query in a explorer window.
ICON | Filename | Optional | Bitmap file which contains the icon of the query.
STYLESHEET | Filename | Optional | XSL file which should be used to generate the HTML output when the query is printed by the end-user. If empty, the end-user will only print XML data.
RENDERER | String | Optional | Name of the renderer to activate when the query result is displayed in a MADCAT explorer window. If this attribute is set, MADCAT explorer window will activate the renderer (if it is available) when the end-user opens the query.
RENDERMODE | String | Optional | Name of the mode to activate. Used only if the attribute RENDERER is set and renderer exists. MADCAT will activate the mode when activating the renderer.
RENDEROPTIONS | String | Optional | List of options to pass to the renderer when activating the mode defined by RENDERMODE. Used only if the attributes RENDERER and RENDERMODE are set. The list of options depends on the renderer (proprietary format) but generally it is a sequence of couple 'option=value' separated by comas.

Child Elements

None

Parent Elements

Name | Definition
ITEM | Go to ITEM definition
FOLDER | Go to FOLDER definition
DATAMODEL | Go to DATAMODEL definition


Definition for element "SERIES"

[image]

MADCAT User Guide
Definition for element "SERIES"
Send Feedback
MADCAT User Guide v1.2.2

Element used to define an series of items of a database. Series are entities which can be created/edited/deleted/selected by the end-user and actions can be performed on them.

Series contains items having exactly the same attributes. The values of the attributes are changing depending on an index value.

The index is defined like an attribute. Two items of a given can't have the same index value.

Use the series if you want to produce tables of values or chart with the dedicated renderers.

Attributes and Elements

Attributes

Name | Type | Class | Description
NAME | String | Mandatory | Name of the item. Used to identify the item in the database. This name should be unique in the whole workspace the model is for. End-user will use this name to refer to the item.
NODENAME | String | Mandatory | Name of the XML element which will be used to store the item data in the database. Used by the end-user in his XPath expressions.
ICON | Filename | Optional | Bitmap file which contains the icon of the item.
STYLESHEET | Filename | Optional | XSL file which should be used to generate the HTML output when the item is printed by the end-user. If empty, the end-user will only print XML data.
RENDERER | String | Optional | Name of the renderer to activate when the item's children are displayed in a MADCAT explorer window. If this attribute is set, MADCAT explorer window will activate the renderer (if it is available) when the end-user opens the item (this feature works only with items having children).
RENDERMODE | String | Optional | Name of the mode to activate. Used only if the attribute RENDERER is set and renderer exists. MADCAT will activate the mode when activating the renderer.
RENDEROPTIONS | String | Optional | List of options to pass to the renderer when activating the mode defined by RENDERMODE. Used only if the attributes RENDERER and RENDERMODE are set. The list of options depends on the renderer (proprietary format) but generally it is a sequence of couple 'option=value' separated by comas.

Child Elements

Name | Multiplicity | Definition
INDEX | Unique and Mandatory | Go to ATTRIBUTE definition
ACTION | Multiple | Go to ACTION definition
TRIGGER | Multiple | Go to TRIGGER definition
ATTRIBUTE | Multiple | Go to ATTRIBUTE definition
INHERITS | Multiple | Go to INHERITS definition
MULTIVIEW | Unique | Go to MULTIVIEW definition

Parent Elements

Name | Definition
ITEM | Go to ITEM definition
FOLDER | Go to FOLDER definition
DATAMODEL | Go to DATAMODEL definition


Tools schema

[image]

MADCAT User Guide
Tools schema
Send Feedback
MADCAT User Guide v1.2.2

Tool schema

The root element

A tool definition file shall begin with the following XML information :

CopyXML
<?xml version="1.0" encoding="UTF-8"?>

then the root element shall be :

CopyXML
<TOOL NAME='<Name of the tool>' LABEL='<Title of the tool>' PATH='<Relative path of the DLL>' xmlns="http://www.themadcat.fr/tools">

Attributes and Elements

Attributes and elements

Attributes

Name | Type | Class | Description
NAME | String | Mandatory | Name of the tool. This name is used to refer to the tool in models (for development only. End-user don't care about this name).
LABEL | String | Mandatory | Title of the tool. This label is used for the end-user interface. This is the name the end-user will see and know.
PATH | Filename | Mandatory | Path (relative to the location of the tool definition file) of the assembly (DLL) of the tool. It can also be an executable file (.EXE).
ICON | Filename | Optional | Bitmap file which contains the icon of the tool. The icon is used in tool bars, configuration panel, etc...

Child Elements

Name | Multiplicity | Definition
DESC | Unique | Simple Text
ACTION | Multiple | Go to ACTION definition

Parent Elements

None


Definition for element "ACTION"

[image]

MADCAT User Guide
Definition for element "ACTION"
Send Feedback
MADCAT User Guide v1.2.2

Declaration of an action performed by the tool.

Attributes and Elements

Attributes

Name

Type

Class

Description

NAME | String | Mandatory | Name of the action. This name is used to refer to the action in models (for development only. End-user don't care about this name). See the elements ACTION and TRIGGER in models.
DESC | String | Mandatory | Title of the action. This description is used for the end-user interface. This is the name the end-user will see and know.
GROUP | String | Optional | Group of the action. When your tool offers a lot of actions, it is recommended to group them by category, sub-category, ... Using this attribute, you can specify the group of the action. The value can be a path built with a serie of strings separated with a slash '/'. Example : "Main category/Sub-category". This value is used by MADCAT to build the "Action" menu of the main form of your application. The hierarchy of your categories will be preserved and transformed into a serie of sub-menus.
ICON | Filename | Optional | Bitmap file which contains the icon of the action. The icon is used in the context menu of the explorer window, button of the tool bar, action's log...
OPTIONS String Optional This value describes the technical possibilities of the action by giving a serie of couple of parameters written like this PARAMETER=VALUE. These parameters should be one of the following :
  • Design-dependent parameters. These parameters are limited to the design of your tool :
    • background : Possible values are 'yes' or 'no'. When set to 'yes', the action will be run as a background task.
    • reentrant : Possible values are 'yes' or 'no'. When set to 'yes', the action will be run immediatly even if the same action is already running. When it is set to 'no', different runs of the action will be scheduled in order to be run one after another.
    • cancelable : Possible values are 'yes' or 'no'. When set to 'yes', the end-user will be able to cancel a running task immediatly. This behavior depends on design. If your code doesn't support this, don't set this to 'yes'.
    • suspensible : Possible values are 'yes' or 'no'. When set to 'yes', the end-user will be able to pause and resume a running task immediatly. This behavior depends on design. If your code doesn't support this, don't set this to 'yes'.
    • permanent : Possible values are 'yes' or 'no'. Set this to 'yes' when the action has no end. When set to 'yes', parameter 'cancelable' should be set to 'yes' too.
    • multiselect : Possible values are 'yes' or 'no'. Set this to 'yes' when the action supports multiple items in the input selection. When set to 'no', MADCAT will schedule automatically as many tasks as the number of items in the user selection. Example : if user selects 4 items then run the action with multiselect=no, this action will be split into 4 different tasks each task handling one item of the selection. When multiselect=yes, MADCAT will schedule one task and your code will handle the 4 items in a row.
  • Other parameters which can be changed without any impact on the tool code :
    • readonly : Possible values are 'yes' or 'no'. When this to 'yes', the data transactions performed by the action won't be commited to the end-user's project. Any modifications performed will be lost.
    • showdetails : Possible values are 'yes' or 'no'. When this to 'yes', MADCAT will open the progress window as soon as the action starts its 2nd phase.
INCOMPATIBILITIES | String | Optional | /!\TBW

Child Elements

None

Parent Elements

Name | Definition
TOOL | Go to TOOL definition


Renderers schema

[image]

MADCAT User Guide
Renderers schema
Send Feedback
MADCAT User Guide v1.2.2

Renderer schema

The root element

A renderer definition file shall begin with the following XML information :

CopyXML
<?xml version="1.0" encoding="UTF-8"?>

then the root element shall be :

CopyXML
<RENDERER NAME='<Name of the renderer>' LABEL='<Title of the renderer>' PATH='<Relative path of the DLL>' xmlns="http://www.themadcat.fr/renderers">

Attributes and Elements

Attributes and elements

Attributes

Name | Type | Class | Description
NAME | String | Mandatory | Name of the renderer. This name is used to refer to the renderer in models (for development only. End-user don't care about this name). See the attribute RENDERER of the ITEM and FOLDER elements in models.
LABEL | String | Mandatory | Label of the renderer. This text is used for the end-user interface. This is the name the end-user will see and know.
PATH | Filename | Mandatory | Path (relative to the location of the renderer definition file) of the assembly (DLL) of the renderer.
ICON | Filename | Optional | Bitmap file which contains the icon of the renderer. The icon is used in tool bars, configuration panel, etc...

Child Elements

Name | Multiplicity | Definition
DESC | Unique | Simple Text
MODE | Multiple | Go to MODE definition

Parent Elements

None


Definition for element "MODE"

[image]

MADCAT User Guide
Definition for element "MODE"
Send Feedback
MADCAT User Guide v1.2.2

Attributes and Elements

Attributes

Name | Type | Class | Description
NAME | String | Mandatory | Name of the mode. This name is used to refer to the renderer's mode in models (for development only. End-user don't care about this name). See the attribute RENDERMODE of the ITEM and FOLDER elements in models.
DESC | String | Mandatory | Title of the mode. This description is used for the end-user interface. This is the name the end-user will see and know.
ICON | Filename | Optional | Bitmap file which contains the icon of the mode. The icon is used in the drop-down menu of the explorer window.

Child Elements

None

Parent Elements

Name | Definition
RENDERER | Go to RENDERER definition


Reports schema

[image]

MADCAT User Guide
Reports schema
Send Feedback
MADCAT User Guide v1.2.2

Reports are used to convert XML data of the end-user's project into HTML.

Report schema

The root element

A report definition file shall begin with the following XML information :

CopyXML
<?xml version="1.0" encoding="UTF-8"?>

then the root element shall be :

CopyXML
<REPORT NAME='<Name of the report>' xmlns="http://www.themadcat.fr/reports">

Attributes and Elements

Attributes and elements

Attributes

Name | Type | Class | Description
NAME | String | Mandatory | Name of the report. This description is used for the end-user interface. This is the name the end-user will see and know.
GROUP | String | Optional | When you have a lot of reports, it is recommended to group them. Give the name of the group in this attribute. This information will be used in the Report window of MADCAT to group the reports of the workspace.
ICON | Filename | Optional | Bitmap file which contains the icon of the report. The icon is used in the Report window of MADCAT.

Child Elements

Name | Multiplicity | Definition
QUERY | Unique | Go to QUERY definition
STYLESHEET | Unique | Go to STYLESHEET definition
PARAMETER | Multiple | Go to PARAMETER definition

Parent Elements

None


Definition for element "QUERY"

[image]

MADCAT User Guide
Definition for element "QUERY"
Send Feedback
MADCAT User Guide v1.2.2

Attributes and Elements

Attributes

None

Child Elements

None

Parent Elements

Name | Definition
REPORT | Go to REPORT definition


Definition for element "STYLESHEET"

[image]

MADCAT User Guide
Definition for element "STYLESHEET"
Send Feedback
MADCAT User Guide v1.2.2

Attributes and Elements

Attributes

Node

Child Elements

Node

Parent Elements

Name | Definition
REPORT | Go to REPORT definition


Definition for element "PARAMETER"

[image]

MADCAT User Guide
Definition for element "PARAMETER"
Send Feedback
MADCAT User Guide v1.2.2

Attributes and Elements

Attributes

Name | Type | Class | Description
NAME | String | Mandatory | Name of the parameter as it appears in the XPath expression. This is case sensitive.
DESC | String | Mandatory | Title of the parameter as it will appear in the dialog box shown to the end-user.
TYPE | String | Mandatory | Type of the parameter. Must be one of the valid type names used in models. See attribute TYPE of element ATTRIBUTES in models.
OPTIONS | String | Optional | List of options relative to the given type. See attribute OPTIONS of element ATTRIBUTES in models.

Child Elements

Name | Multiplicity | Definition
ENUM | Multiple | Go to ENUM definition

Parent Elements

Name | Definition
REPORT | Go to REPORT definition


Workspace management

[image]

MADCAT User Guide
Workspace management
Send Feedback
MADCAT User Guide v1.2.2

This section contains important information about workspace management. This topic may be very important if you plan to build several workspaces and optimize the management of your tools, models and renderers among these workspaces.

This section is addressed to the expert users of the MADCAT who want to build applications based on the usage of a system of workspaces.


Main Principles for Workspaces management

[image]

MADCAT User Guide
Main Principles for Workspaces management
Send Feedback
MADCAT User Guide v1.2.2

This chapter explains how to manage your workspaces.

Workspace architectures

First a workspace is a place to do some specific tasks. To do that, you need data, macros to help you and a good interface. In MADCAT, data is your project, macros are provided by the tools, the interface by the renderers.

Of course you can create a workspace where you could do a lot of tasks with tons of data but most of the time this kind of place are difficult to maintain and to share with other people.

So MADCAT also provides mechanisms to split your work in several workplaces and minimize redundancy of tools and renderers in your system. Then you can setup 2 different architectures :

  • star shaped systems : one central space owns the tools, renderers and the models and share them with many workspaces which own the data.

  • cloud system : no central space but each workspace can share its models, tools and renderers with one or several other workspaces.

The prefered architecture is the star shaped one, so a new concept is now introduced with the release 1.2 : the repository.

Workspace Repository

The repository is a storage place for templates of workspaces. Templates are workspaces like others but with no data. It contains only models, tools and renderers. You should never work inside the repository but use it to gather all your tools, models and renderers and organize them in categories. Two ways of filling your repository :

  • from scratch : make your own tools and renderers with Visual Studio Express and create templates with the workspace editor

  • from existing workspaces : copy the tools, models and renderers of a workspace to the repository using the workspace management tool (tmwrkmgr)

Once your repository exists, you can rapidly create new workspaces in your system with the workspace management tool (tmwrkmgr) :

  • give it a name

  • setup the graphical appearence

  • select the tools, models and renderers from the repository

  • select your data sources

and that's all : your workspace is ready to use and contains only the data, the bitmaps and the workspace definition file.

Because nothing is never frozen inside MADCAT, you can add specific tools, renderers and models to this workspace. Post them to the repository.

Or you can change your configuration by taking new things from the repository and removing some others you don't need.

New way of thinking softwares

With the workspaces of MADCAT you fit your application to your real needs.

Normally when you want to do something on your computer, you install and use a software which offers tons of functions but you will only use a small number of them. Your interface is full of menus, buttons and windows. You can rarely change them as you want. It is difficult to update them as you want and most of the time you have to follow the editor's choices.

With the MADCAT architecture, software functions come in the smallest form : a piece of model, one tool and one renderer. Model will control the way data should be formatted and stored in your project. It also links data to the tool and the renderer. Then you combine all this elements to make your own application : it can be very simple or complicated, MADCAT doesn't care. It's up to you to select the elements you want for the task you want to do on your computer.

And because this task can evolve in time (new perimeter, new requirements, etc...), you can always transform your application as you want : you control everything.

So if you plan to develop tools and renderers, think about the model first. Make as simple and generic as possible. Remember that inheritance and polymorphism can help you combine simple models to build complex items.

With your simple model, develop macros in your tool (actions) and dedicated user interfaces in your renderer.

Example of the flexibility of MADCAT

in a model named "BASEGRAPHICS",

You can define an item named "BOX" which has 4 parameters : X,Y,Width and Height

Develop a renderer "BOXRENDERER" which will display a rectangle using the parameters of "BOX" items.

Develop a tool which can "inflate" or "deflate" a "BOX" item for a given amount of pixels (using a dialog box for example).

Associate these 2 actions ("inflate" or "deflate") to the "BOX" item in the model.

Associate the renderer "BOXRENDERER" to the "BOX" item in the model.

Now, you can create a workspace with only "BASEGRAPHICS" and its tool and renderer.

You'll be able to manage rectangles in your project.

Then, in a model named "UIGRAPHICS",

you can define a new model item named "BUTTON" which inherits "BOX". Add one parameter "NAME" to the item "BUTTON".

Add this model in the workspace.

You'll be able to manage buttons and rectangles in your project.

Finally, in a model named "EXGRAPHICS",

you can define a new model item named "BOX" with one parameter "HELP".

Develop a renderer "EXBOXRENDERER" which will display a rectangle with help in it using the parameters of "BOX" items.

Add this model in the workspace.

All the previously created rectangles and buttons have a new attribute you can fill.

You can use both BOXRENDERER or EXBOXRENDERER to display the items.

If you want you can remove BOXRENDERER.

Note
Note that these operations (adding/removing models, tools or renderers) can be done in few seconds without programming knowledge. These operations will never corrupt your data. Data is preserved at anytime.


Manage workspaces from the Windows explorer

[image]

MADCAT User Guide
Manage workspaces from the Windows explorer
Send Feedback
MADCAT User Guide v1.2.2

To quickly manage your workspaces, the MADCAT integrates into the Windows' Explorer its workspace manager. This chapter explains how to use the workspace manager through the explorer or directly from a command line.

Add a workspace to the repository

Any existing workspace can be copied to the repository. This operation copies the elements of a workspace to the repository in order to share them with other workspaces.

When you copy a workspace to the repository, only the MADCAT elements are copied : tools, models and renderers.

To copy a workspace to the repository, follow this simple procedure :

  1. Right-click on the definition file (XWS) of the workspace you want to copy

  2. Select a category within the repository

  3. The workspace is copied. A detailed log is built to show you the operations done by the manager.

Once copied, all the elements of the workspace are available for any other workspace in your system.

This is the easiest way to share the same model, tool or renderer without copying it several times.

Create a new workspace with the repository

Another cool feature of the workspace manager, is the ability to create new workspace directly from MADCAT elements taken from the repository and without using the Workspace Editor.

The objective is to facilitate the workspace creation process because the flexibility of MADCAT is based on the capacity of sharing data among several workspaces; each one being dedicated to one specific task within a given process.

To create a new workspace from the repository, follow this simple procedure :

  1. Right-click on the folder where you want to create your workspace

  2. Fill the workspace properties with the wizard

  3. The workspace is created. A detailed log is built to show you the operations done by the manager.

The new workspace is ready to use. The elements are not physically copied to the selected folder. They stay in the repository. So all the workspaces created this way don't take a lot of space on your hard disk. Only the data you'll create in it will use hard disk space.

Using the command line (Expert users)

the MADCAT workspace manager can also be started from the command line and it supports several commands :

Command | Description
-r WorkspaceDefinitionFile | Copy the elements of the selected workspace to the repository
-c WorkspaceFolder | Create a new workspace using elements of the repository into the folder WorkspaceFolder


Customize workspaces from the configuration panel of the MADCAT

[image]

MADCAT User Guide
Customize workspaces from the configuration panel of the MADCAT
Send Feedback
MADCAT User Guide v1.2.2

The configuration panel

The configuration panel provides access to the configuration settings of the current user for :

  • Databases
  • Tools
  • Renderers

See the section the Configuration Panel for a description of the configuration panel.

Change the elements of the workspace

When the workspace is not locked (see Workspace schema for details about that), the user can add or remove elements to the workspace

Remove elements

Just right-click on an icon of the configuration panel and click on "Remove"

Config Panel Remove Element
Note
Elements can only be removed one by one.

Add elements

Just double-click on the extra icons (the ones with a yellow star) of the configuration panel

Config Panel Add Elements

This will open the repository browser :

Select a workspace in the repository with the sliding slices on the left of the window. The elements available in this workspace appear on the list on the right part of the browser.

Choose one selection rule above these 3 :

  • Don't use these elements

  • Use all these elements except those selected below

  • Ignore all these elements except those selected below

Check the elements you want to add or ignore (regarding the rule you selected)

Click on "OK"

The new elements will be displayed right after the extra icon (on its right side)

Apply changes

Modifications (add or remove) are actually saved to the workspace definition file only when you click on the button "Apply" placed on the bottom of the configuration panel. If you quit the configuration panel without clicking on it, all the changes will be lost.

Configuration Panel With Apply
Note
When you click on "Apply", the MADCAT restarts your workspace. If you made changes on your data, the MADCAT asks you to save them to disk before restarting the workspace.