Conceptual overview of the OLAT interaction design. Shaded entities are not in the scope of this chapter.

The most important layout elements used in OLAT

Since OLAT is a dynamic webapplication and not a static website the whole layout and navigation is generated on the fly and can't be changed by the common user. You can still customize the look and feel of your OLAT installation, this is explained in Customizing. For navigation in OLAT we separate the page in four parts: top navigation, content menu, content area and toolbox actions.

The interaction design is characterized by consistency regarding position (relative and absolute), structure, semantics, and function. I.e. interaction elements of similar types or conglomerates thereof

The following guidelines do not act as laws of nature, you will certainly find exceptions in OLAT. But (intended) guideline deviation should be well-founded and should result in better usability.

In OLAT there are four basic system roles. Those roles are assigned as a basic set of rights. You can add users to those system roles in the Administration area within OLAT. Additional rights can be defined individually as well in the Administration area. The system roles are, in short:

See also Section 2.6, “Groups” to learn more about the differences between groups and system roles.

OLAT provides an abstract mechanism of authenticating users. In the olat_config.xml configuration file in section LoginModule you'll find a set of authentication providers which handle authentication and authorization. This is simply a class which extends AuthenticationController , hence you'll have full control over the workflow needed to authenticate your users. All authentication providers listed in the config file (and enabled) will be presented to the user on the login screen. The user may choose the way she wishes to authenticate herself.

At the time of writing, there are four implementations of AuthenticationController: OLATAuthenticationController implements a simple username/password authentication, ShibbolethAuthenticationController implements authentication based on Shibboleth 2.0 and the SWITCH Embedded DS (see the Section 2.7, “Shibboleth” for details on this method of authentication), DefaultShibbolethAuthenticationController just provides a link for redirecting the requests to the /shib/, and LDAPAuthenticationController which implements auth. based on an LDAP backend server.

The authentication provider system is also used for other authentication purposes where an authentication is needed.

First of all the RepositoryHandlerFactory is the central point where the implementations of the RepositoryHandlers are subscribed for the types they claim. By design the type should be the string returned from the OLATResourcable.getResourceableTypeName() .

All resources in the repository refer to a file so far, but the type - handler mechanism is restricted by no means to files. The following table maps file resources and their suffixes to the corresponding handler.

The file validating class is used to check whether a certain file or archive is valid. The Handler class is responsible for a starting point of GUI workflows for the corresponding file or archive. It inform the RepositoryHandlerFactory about possible actions (see the section called “Workflows”) and which types it handles.

Managing the repository involves adding, creating new resources, removing existing ones and update the meta information of a repository entry. Adding involves either uploading a file resource or selecting one from the various folder places. Creating is typically only possible if OLAT offers the appropriate editor.

Figure 2.2. The actions on the repository.

The concrete implementation of the RepositoryHandler, i.e. WebDocumentHandler, must provide a controller for adding the given resource. This controller is returned when the getAddController(..) method is called.

Before a deletion is issued the handler of the respective resource is asked if the resource is readyToDelete(..). The deletion is initiated by cleanUpOnDelete(..) which is expected to do any work necessary, before removing the resource definitively.

Similiar to the adding of a resource, the handler also may provide the facility to create or edit the resources meta information. This is the so called details view and a component for this can be provided in the method getDetailsComponent(..).

Figure 2.3. How the repository looks.

The course is hierarchly structured - a tree - whereas each course node represents a building block. Such a building block is an encapsulated functionality for the course. These building blocks can be divided into the categories Content and structure , Assessment and Scoring , Collaboration . Each building blocks can control access and visibility with help of the visibility and accessability rules . Following building blocks are implemented so far:

The CourseFactory ensures that a course is loaded only once into the RAM. Thus all cours participants, tutors, authors are sharing the same course object. It is clear that each course user must have its individual course run session where user specific data is processed. To accomplish this the course has a UserCourseEnvironment which holds the user specific course run data. Besides this the CourseEnvironment aggregates runtime course information which again is shared between all users.

The course is made persistent with the XStreamHelper using XML object serialization. Because of the sophisticated publish mechanism there is a persistent valid course editor xml tree structure and a valid course run xml tree structure co-existing. The course run is the users view to the course, and the course author sees the course in the editor view.

The author can select specific or all changes in the course editor to be published into the run structure. This process is defined in the PublishProcess and controlled from the PublishController roughly speaking it consists of:

Each course has associated a course configuration which is persisted as XML file in the same place as the run structure and editor strucuture files.

This settings contain so far configurations for:

If a new configuration must be added one has to follow the guidelines described in CourseConfig . Special care must be taken to increase the CourseConfig 's version number, once a change was active in a productive environment.

This rules are specified like arithmetic expressions, whereas the valid functions and units are registered in the ConditionInterpreter. Each building block has associated a visibility and accessability condition which is recursively evaluated during the users course run. Once a building blocks visibility or accessability is false the child nodes are not evaluated.

Some of the course building blocks are of type AssessableCourseNode. The assessable course nodes use the AssessmentManager from the course environment to set and get assessment information.

TODO:More info on this will be added soon.

See Section 2.6, “Groups”

See Logging and Statistics

OLAT includes an editor for QTI files. The editor offers single and multiple choice, fill in blank and free text as type of questions (the latter only in surveys). Since QTI does not define different types of questions, the editor relies on a nameing scheme to identifie the type of question. This is done via an encoded item id in the form QTIEDITOR:SCQ:123 where QTIEDITOR denotes that this item was created with the OLAT editor, SCQ denotes the type of question (other types are MCQ, FIB and KPRIM) and finally the number is a file unique ID. See QTIEditorHelper for details.

It is important to note, that the editor does not allow to work with arbitrary QTI files created by other editors or manually. It can only edit questions which originate from the editor itself. If you do any manual changes to the generated qti.xml file, your changes may get lost when loaded again in the editor or the item may not be editable anymore. The qti.xml is parsed and converted into an internal structure within the editor. Upon saving the file, the qti.xml is generated from scratch based on the internal structure.

The QTI runtime implemented within OLAT can handle almost all features of QTI 1.2.1, much more than the editor can actually handle. So you may not be able to edit files generated manually or by external editors but your files are most probably fine for the runtime.

The runtime allows tests to be resumed in case the user's browser crashes. For this, a dump of the whole runtime information is written to the filesystem after every response. These files are stored in PATH_TO_OLATDATA/qtiser/USERNAME/QTI_RUN_ID/qti.ser . If the user starts the test again, the workflow will resume based on the information stored in this file and the user should start again from where she left last time.

The results of a test run are stored in XML files based on the IMS QTI Results Reporting standard. The source of the questions is added to the results reporting for further reference. The files are stored in PATH_TO_OLATDATA/resreporting/USERNAME/QTI_RUN_ID.xml . The results reporting XML is transformed with a stylesheet to present the results in HTML to the user. You'll find the stylesheets in the package org.olat.ims.resource.xsl. The stylesheets come in different languages where the language specific strings are defined in the prologue. This is the last bit of XSLT within OLAT.

In a real world test situation, people may not want students to be able to exchange information with each other during the actual test. For this reason, if in a test (this does not aply for self-tests of surveys), all collaboration tools will be disabled. These include the instant messaging system and the buddy groups for the specific user. All collaboration tools will be re-enabled, when the user successfully finishes her test.

First it is important to understand which groups we are talking about. There are several places in OLAT where you can add users to a group:

In this chapter we talk about the generic business groups concept and where it is used within OLAT.

The BusinessGroup class is a concept for a group that serves the purpose of collaborating, working or doing something together. The BusinessGroup is abstract in a way that it generically implements a set of functions that can be usefull when working in a group. However, in reality we deal with concrete groups that serve a special purpose and will use only a subset of all functions available in the generic BusinessGroup. To distinguish these concrete groups we give the BusinessGroup a field called groupType .

When thinking object oriented you could create an abstract superclass and use inheritance to create the concrete implementations. However, when persisting such a construct using a object-relational mapping layer like hibernate it can easily get complicated. Therefore we decided to make it differently and implemented one generic BusinessGroup together with one generic BusinessGroupEditController and one generic BusinessGroupMainRunController . The controllers offer the complete set of functions implemented by the generic BusinessGroup. When creating these controllers using the BGControllerFactory a configuration object BGConfigFlags is used to tell the controllers which functionality is enabled for the concrete group that is displayed or edited. This way the controllers must not know anything about group types, they only know which feature to display and which one to hide. Adding new features to groups or changeing features is only a matter of implementing the generic functionality in the businessgroup and the controllers and then enabling it in the configuration for all group types you want.

A BusinessGroup uses two SecurityGroup labled owners and participants. A SecurityGroup is a generic implementation of a group without any context or business meaning by itself. The meaning of those two underlying groups in the BusinessGroup class is that members of the owners security group have the right to modify / manage the business group wheras members of the participants security group do not have such a right.

Correlation between group context, groups, areas and courses

Every BusinessGroup has a reference to a BGContext and the BGContext has references to OLATResource. The idea of the business group context is to define the context in which the group is used.

Groups of type BuddyGroup are an exception since they have no dependecies to any OLATResource, thus they have not context defined (NULL)

The BGContext serves as a container for all groups that belong together. It has a type which means that a BGContext can only have groups of one type in it. BGArea, as we see later, do also belong to a BGContext.

Group contexts are used in course to manage groups. Every course has at least one group context for the type LearningGroup and one for the type RightGroup. When creating a new course a new learning and right group context is generated and labeled as a default context. A default context means that this context has been generated automatically for the purpose of the groupmanagement within this course. It is only good for this course.

In most situations this is fine and everything works as expected by using this default group contexts. But in some cases it makes sense to use the same groups in several courses. This is also called course comprehensive groupmanagement.

To achieve this it is possible to create BGContext that are not labled as default context. These group contexts are created manually in the groupmanagement site that is only available to users with the system role administrator or groupmanagement. Those BGContext do use a SecurityGroup to manage the owners of this context, to define who is allowed to manage this group context. To those contexts the owners can add one or more OLATResource (meaning courses) where this groups should be used.

Note that you can have more that one group context added to a course. When launching the groupmanagement in the course you then have to select which group context you want to manipulate. Everyone who has access to the groupmanagement within a course can modify the groups as if it where a default group context containing course internal groups. They do not need to be in the contexts owner security group.

A BGContext can have so-called BGArea relations. An area has a name and description and is used to associate many groups to a certain area of a course. In the GUI we call it learning area.

You can see areas as a group of groups, however a group can be in more than one areas, thus it is not really a group of groups. You could also see an area as a group attribute, a tag that you stick on a group.

From a paedagogical perspective it makes sense to ask “are you in group red, blue or green”, then do something. However, this gets very complicated with may groups. It would be much easier to ask “are you in a color area” and then add all your groups to this color area. This is what the BGArea is good for: address and organize groups that fullfill the same purpose.

Example: create an are enrollment and add your groups Class Monday, Class Friday to this area. In the enroment course building block use the area instead of the group names to define which groups can be used for enrolment. OLAT automatically offers the user all groups of the defined learning area to enroll into.

You can also use the areas to define learning activities and associate groups to this activities. In the course building blocks you then restrict access and visibility of certain blocks to groups that participate in the named activity.

Areas are only used by business groups of type LearningGroup

Group rights can be associated to a BusinessGroup. All possible rights are defined in CourseRights, a right is nothing more than a string that has a business meaning. Using the BGRightManager it is possible to ask OLAT wheather a user has a certain right in a certain group contex.

Currently group rights are used in course right groups to grant full access to the course editor, the assessment tool, the groupmanagement or the archive tool.

Rights are only used by business groups of type RightGroup

Since the whole BusinessGroup codebase is completely contextless implemented and uses the same code for buddy, learn and right groups a special issue must be covered and this is localization. On screen the generic code must have group type dependent locales. In some locale strings only the group type differs, in others it makes sense to have different sentences like when sending mails after beeing added by someone in a group

To solve the problem of one generic code and multiple translations depending on the type we use the translator fallback mechanism. Each Translator can have its fallback translator in case the key is not found. This way it is possible to build a chain of translators. The GUI controllers of the group package use the BGTranslatorFactory to generate a package translator that use a group type translator in the first position of the translator chain.

In the package org/olat/group/ui/run a certain key is used to display someting in a group, e.g. a title. As soon as you define the same key in the package org/olat/group/ui/buddygroup or org/olat/group/ui/learninggroup the key from the group type specific package has precedence and is used for translation.

Each BusinessGroup has CollaborationTools that are used in the groups run time environment to communicate and share data. The collaboration tools are generated using the CollaborationToolsFactory and are not group type specific.

The group owners or administrators can enable and disable the collaboration tools in the edit mode of the group on a group level.

Currently we have the following tools available:

The BusinessGroup allows synchronization of group members with your Instant Messaging roster list. This features is only available when the Instant messaging module is enabled.

Synchronized groups appear in the top navigation night next to the IM status. In brackets two figures are show: number of online buddies and number of total buddies. Buddies in this terminology are users that are in a buddygroup that you participate.

IM roster synchronization is only enabled for business groups of type BuddyGroup and can not be configured.

When a user first successfully authenticates herself via Shibboleth, she must register with OLAT. The user is asked for a username which identifies the user within OLAT. A user profile is generated and the email address provided by the Identity Provider's Attribute Authority is automatically added to the profile. This implies that an Identity Provider's Attribute Authority must at least provide an email address attribute. Furthermore, a unique identifier is needed which is configurable per site in the olat_config.xml. After accepting the disclaimer, the user is forwarded to the home screen and registration is completed.

Shibboleth SP provides attributes of a user to OLAT. These attributes are propagated within OLAT upon each successful authentication. The attributes can be used within course building blocks to define access and visibility rules. Note that these attributes are not persisted, except for the unique identifier (used to associate an authenticated user to its OLAT user profile) and the email address.

For easier handling of attributes, you may define a set of attribute translations in olat_config.xml. Attributes will be available by their translated name (outName) within OLAT. For example, a standard attribute defined by Shibboleth is Shib-InetOrgPerson-givenName which is both hard to remember and enter into form fields. With the attribute translation map, you can translate this attribute's name to givenName and reference it in your accessibility and visibility rules with its translated name.

DefaultShibbolethAuthenticationController just provides a link for redirecting the requests to the /shib/. The user is farther redirected to the central WAYF, and upon selection of the IdP, to the IdP authentication page. Upon successful authentication the user is redirected again to OLAT.

Login sequence with DefaultShibbolethAuthenticationController: OLAT Login page: Shibboleth Login - DefaultShibbolethAuthenticationController > Redirect to /shib/ > mod_shib > Redirect to WAYF, choose IdP > Redirect to IDP > IdP Authentication > redirect to the Service Provider that protects this Resource (see SP configuration in shibboleth2.xml) > OLAT (ShibbolethDispatcher - retrieves the attributes)

SWITCH Central WAYF

Authenticate to your IdP

ShibbolethAuthenticationController uses the SWITCH Embedded DS. It basically works like the one above, except that the user already gets directly the WAYF on the login page.

Login sequence with ShibbolethAuthenticationController: OLAT Login page: Shibboleth Login Embedded WAYF, Choose your IdP (ShibbolethAuthenticationController) > Redirect to IDP > IdP Authentication > redirect to the Service Provider that protects this Resource > OLAT (ShibbolethDispatcher - retrieves the attributes)

SWITCH Embedded WAYF

Authenticate to your IdP

In the settings area of the home site the user can personalize OLAT. This means language, font size (three different CSS for small, medium, large), instant messaging preferences and personal attributes like birth date. A language change will only be activated at the next login. See also

If you need more user properties see olat_userconfig.xml for custom configuration of user properties.

In WEB-INF/olat_config.xml in the section org.olat.user.UserModule offers some more configuration options for user settings.

The home site has a portal entry page. The portal can be configured. This means the portal elements, so-called portlets, can be moved around in the portal and portlets can be activated / deactivated. The state is persisted for each user in the GUI preferences. See the section called “GUI preferences” for more info about this.

The portal, the portlets and the default portal configuration is defined in WEB-INF/olat_portals.xml . In the PortletFactory part all known portlets are defined giving them an identifyer called name. In the second section, the PortalFactory, two portals are defined: the homeportal and the guestportal

Every portal has a map called portletsConfigurations. In this map all portlets allowed in this portal are listed. The key identifies them within the portal. The values are portlet configuration values that are handed over to the portlet when launched. One special value is called portletName which referres to the name of the portlet defined in the PortletFactory.

Every portal has a list called portalColumns. This is the default list of activated portlets used whenever the user has no personalization made. The list contains lists (the portal columns) which contain references to the portlets configurations above.

Every user has a personal space to store files. In the users personal folder two virtual subfolders are present, the private and the public folder.

The private folder is only visible and accessable to the owning user. The public folder can be accessed by all OLAT users using the search workflow also located in the home site. Other users have only read only access to other users public folders. To share data in both directions one can use the project groups which does also feature a folder.

The personal folder can be mounted using WebDAV, see next chapter on this.

Every user has his own visiting card to expose more or less of his personal data to all registred OLAT users. He can upload an image and enter a text in Wiki syntax to appear on his card. In addition his public folder is visible to other users und he can be contacted by email via the contact form. If the user posts a message to the forum, the uploaded image will be integrated into the message header. Via the usersearch form a user, respectively his visiting card can be found.

The visiting card should be embedded as link wherever more information on a person should be displayed like for example in a forum post. To generate such a link together with the users portrait foto use the DisplayPortraitController.

OLAT has a fully compatible SCORM 1.2 runtime environement. Due to some SCORM concepts it differs a lot from the IMS content packaging viewser also integrated in OLAT. Each content object (Sharable Content Object [SCO]) communicates with OLAT over a separate channel with backend while the user is browsing the content. The API each SCO is looking for consits out of 5 javascript functions that need to be present in the SCO content.To communicate with the backend we relay on the not yet so commonly used XMLHttpRequest javascript object. It allows us to do asynchronous SCORM API call without the need for an Java Applet or other plugin technolgies.

The SCORM backend consits of three parts. First part is a standard OLAT controller which listens to the SCORM API calls and passes them further to the SCORM backend. The controller delivers also the content which is displayed in an IFrame. The API calls are passed to the API Adapter which is used in other projects as well (Ilias and ATutor).

All folders accessible through the GUI within OLAT are managed by the FolderRunController. The actual file operations are further wrapped by a Virtual Filesystem (VFS). See the section on the section called “Virtual Filesystem (VFS)” VFS for further details. Folders can have security restrictions such as read/write restrictions and quotas. All this is implemented through the functionality provided by the VFS abstraction layer.

All of a user's folder are exported via WebDAV through a single unique mountpoint at webdav://your.server.com/olat/webdav/. The user authenticates via an OLAT authentication provider (see section on authentication) and is presented its personal briefcase, and any coursefolders/groupfolders/sharedfolders she might have access to.

After log in the home site is activated. However, it is also possible to directly jump into a course, forum in a group etc. When creating new sites or dynamic tabs this is handled via ControllerFactory.createLaunchController(). When the site or dynamic tab already exists the activation is done through the Activateable interface that must be implemented by such sites.

OLAT should be easy to use without the need to read help. However, the functionality of OLAT is so big and some of it is quite complex that it is not possible to make everything self explanatory. The context sensitive help is used wherever some help might be needed. The context sensitive help is appears with a small symbol. By clicking the symbol a pop up window opens containing the help.

The context sensitive help is placed in the html files using the velocity helper rendering method velocityRenderDecorator.help(). The context sensitive help is written using the translation tool explained in Customizing.

The comprehensive help in OLAT is accessed via the top navigation tools. The help opens in a new window and is organized as a regular OLAT course. This is very handy since the help has also a forum. Make sure you register to this forum notifications!

The OLAT help course is imported when starting OLAT. Modify the lines in the module CourseModule in the WEB-INF/olat_config.xml file if you want to have your own help course used instead of the default one.

Some GUI elements in OLAT offer configuration / personalization options. These options usually have a very local scope and do not influence the whole system. In contrary the users settings that can be changed in the home site (see the section called “Settings”) have a global scope and affect OLAT as a whole for this user.

Every user has one object GuiPreferences that can be retrieved from the users user session ureq.getUserSession().getGuiPreferences(). The GuiPreferences object offers then methods to get and set values for this user.

The users list in the group management for example features much more data than is shown in the default view. However, presenting all data would make the table very large and would force you to scroll vertically. In this table a small icon right on top of the table lets you customize this tables view. Some other tables also use this feature, e.g. the listing of learning resources has an additional date field that is not visible in the default view.

Another place where the GUI perferences are used are the menu and toolbox state. Menus and toolboxes can be put into a dynamic / hidden state. This state information is stored in the GUI prefereces.

Another example is the home site portal configuration. The users personal settings are also stored in the GUI preferences.

The OLAT Application is primarily a servlet application which simply needs a servlet container (e.g. tomcat) to run. It uses a lot of opensource frameworks to get its job done. The most wellknown are

The GUI framework is a self-developed framework, which is component-based, follows the MVC (Model-View-Controller) paradigm, and focuses on reuse of component and also of workflows. It is a lot like Java Server Faces, but more powerful. Programming the GUI is very similar to developing with SWING or SWT. We have panels, Containers with layouting, pre-built components like links, forms, tables, and so on. The workflows are grouped into reusable controller classes, so that e.g. a user search (a search form, then a list of found matches) can be reused all over the places

The framework can support any language since it saves both localization and user data in utf-8. Even mixed content (content packaging with some encoding other than utf-8) works fine. There is an online translations tool within olat so that translating into a new language is a piece of cake (but still a lot of work!!) See Customizing

The OLAT programming concept can summarized as follows: Swing like - Component based (MVC), Business task (Controllers), Business logic (Managers), use of well established open source libraries

Here is a very general overview of OLAT and its concepts.

A Component is a visual representation of e.g. a Link, Form, a Table and so on. One ore more Controller can listen to Event which are fired when the user e.g. submits a form. Each component must provide its HTML-Renderer (method getHTMLRendererSingleton (interface ComponentRenderer) which know how to render its state in HTML.

Business logic is encapsulated in Controller classes (and the Manager classes they use), whereas the layout can be controlled by mainly modifying CSS. Almost all images can be configured using CSS also. In case you really would like to dig even more into the layout, you can easily change the HTML-Fragments which is HTML-Code with some Velocity commands in it

The GUI Framework has mainly two things to do upon each browser-click from a user:

With the release 5.2.0 OLAT introduced a significant improvement in case of user experience and architectural change. The component architecture allowed us to easily switch to a mode where the components come in play up to the browser client.

In non ajax mode all components where rendered on the server and concatenated to a big html file and delivered to the client which rendered the whole page for each click. The ajax mode allows now to just send the components that are dirty to the client and the client renders the html fragments into the GUI by dom replacement. As we do this on component level the whole process is transparent for the developer and therefore very little special effort is needed by the developer to achive this.

To make sure everyone gets the best OLAT experience the ajax mode only gets automatically enabled for fully tested browsers. See the olat-config.xml file for a list of supported browsers. The not supported browser get just the normal request based full layout page with each click.

OLAT helps the developer with several built-in features. These should be disabled in a productive environment.

The GUI debug mode helps in understanding the GUI stack structure. It is then easy to find out why something does not show up where it was intended to, see Figure 3.2, “GUI debug stack” . Refreshing the velocity pages and the refreshing localized string properties enable the developer to change/fix broken layouts and translation keys on the fly. The yellow highlightend component, visible in Figure 3.3, “GUI debug listeners box” , produces a floating box with additional information:

Figure 3.1. Select Debug Mode

Figure 3.2. GUI debug stack

Figure 3.3. GUI debug listeners box

The OLAT framework works with the unchecked exception principle. This means that the developer should not care about exceptions in general. Exceptions go there long way up to the top level of OLAT, where they are catched and translated into a red screen, see Figure 3.4, “Red screen of an unchecked exception.”

In a productive environment a user only gets the Error code and the Date and time information, which she should present to the support. The system administrator can retrieve within OLAT the associated stacktraces and errormessages for further measures.

Figure 3.4. Red screen of an unchecked exception.

To get an overview and also have some good starting points for sample code login to OLAT as adminstrator and check if you see the main tab (GUI Demo). This tab shows you most of the visual elements of the OLAT framework in action. To access the sourcecode just click the view source code link (source shows you the java source and velocity the html fragments). If you cannot see the tab it is not enabled. To enable it go to te olat_extensions.xml file and uncomment the spring bean: olatsites_guidemo and restart OLAT. You can also debug the whole GUI by starting OLAT with the brasato.debug=true in the olat.properties file and restart OLAT. The green bug in the upper left corner lets you explore the GUI and lets you view the underling source by clicking the links. See also chapter:GUI debug stack.

For easy reference the OLAT demo server should also be setup with the settings above.

The (HTML) attribute values (see Velocity pages or in Renderers) could contain DB stored data (e.g. long course name becames an alt attribute) or a translated string (found in LocalString*.properties).

The HTML attribute values (in Velocity pages or in Renderers) must be HTML escaped (using org.apache.commons.lang.StringEscapeUtils.escapeHtml), else could break the javascript:

- use example in Velocity page: alt="$r.translateInAttribute("import.example")"
- use example in renderer: sb.append("\" title=\"" + StringEscapeUtils.escapeHtml(title) + "\">");

See org.apache.commons.lang.StringEscapeUtils and org.olat.core.gui.render.velocity.VelocityRenderDecorator.

We must avoid using HTML attribute values with single quotes, since it not possible to escape using the StringEscapeUtils methods. The translated strings used in non-attribute values doesn't need escapeHtml. (see GUIMessage.renderError) See also org.apache.commons.lang.StringEscapeUtils.escapeJavaScript.

If you like to develop some extensions or just play with the sourcode and debug some workflows of a running OLAT you will need to run OLAT out of the Eclipse IDE. You can download the great Eclipse IDE including the necessary web tool plugins here

A step by step guide on how to set up Eclipse with OLAT can be found here.

To extend OLAT, you add one line in the olat_extensions.xml file pointing to your extension, and place your extension.jar file in the WEB-INF/lib directory. For starters, see the package ch.goodsolutions.demoextension or com.xyz.demoextension in the normal OLAT source code distribution.

// In your module, listen to channel. Your module must implement the GenericEventListener interface.
coordinator.getEventBus().registerFor(this, null, PersistingManager.IDENTITY_EVENT_CHANNEL);		  

// Listen to events:
/**
 * Receive the event after the creation of new identities
 */
public void event(Event event) {
	if (event instanceof NewIdentityCreatedEvent && autoSubscribe) {
		NewIdentityCreatedEvent e = (NewIdentityCreatedEvent)event;
		Identity identity = ManagerFactory.getManager().loadIdentityByKey(e.getIdentityId());
		doWhateverYouNeedToDoWithNewUser(identity);
	}
}
		  

In short: write your new code (ch.goodsolutions.demoextension or com.xyz.demoextension), deploy the code as a jar, add a line in the olat_extensions.xml, restart olat.

classes  --> YOURPACKAGENAME/yourclass.java
content (velocity templates) --> YOURPACKAGENAME/_content/yourcontent.html
css files (static content) --> YOURPACKAGENAME/_static/css/yourcss.css
image files (static content) --> YOURPACKAGENAME/_static/css/img/yourimage.png
js files (static content) --> YOURPACKAGENAME/_static/js/yourjs.js
translations (properties) --> YOURPACKAGENAME/_i18n/LocalStrings_en.properties

 <!-- generic OLAT extensions -->
 <bean id="extmanager" class="org.olat.extensions.ExtManager" singleton="true">
  <property name="extensions">
   <list>
    <!-- classes implementing the Extension interface -->
    <!-- add your extensions here! -->
    <bean id="demoextension" class="ch.goodsolutions.demoextension.DemoExtension" singleton="true" />
   </list>
  </property>
 </bean>

    

A controller is a reusable business-workflow (see also above 'Layers in short'). A controller has the following responsibilities:

A controller can use:

Please see the javadoc of each controller to see what it is for. Briefly there are:

See the java classes extending the Defaultcontroller class

Managers within OLAT are conceptually responsible for providing the basic functionality to the workflows (i.e. controllers implementing the actual workflows). Managers usually provide persistence functionality such as storage in the database or on the file system. In general, no workflow should directly deal with the filesystem or the database, it's all handled through a dedicated manager implementing this functionality.

We could have used ResourceBundle from the Java SDK, but you cannot clear the cache which is annoying for translation. Since we use java.util.Properties, the encoding is assumed to be iso_8859_1 (see java.util.Properties). However, if you use the online translation tool (Administration / Online translation tool) you can work with input in any encoding (just submit the form...)

The i18n system is described in a separate document "Understanding the Internationalization (I18n) and Translation System"

The browser always sends it page in utf-8. encodings from resources like html files from content packages are converted automatically

If The browser always sends it page in utf-8. encodings from resources like html files from content packages are converted automatically

A Mapper is used to route a certain url directly to some place in code. This is useful if you want to e.g. deliver static resources.

Properties are used in very many places in OLAT und persisted in the table o_property. A property is a data container and has at least one name apart from its id and lastmodified date. Addionally it has several fields (category, floatvalue, stringvalue, textvalue, etc.) to store more information depending on the context it's used. If some of this fields are not used, they can be null. Creating a new property, you have to think about how to retrieve it. Adding several properties to a already used or new specified category, you can easily retrieve them.

PropertyManager pm = PropertyManager.getInstance();
p = pm.createPropertyInstance(null, null, null, "_o3_", "InfoMsg", null, null, null, "");
       
pm.saveProperty(p);
  
Property p = pm.findProperty(null, null, null, "_o3_", "InfoMsg");
       
pm.deleteProperty(p);

The DB is used as the main and only entry point for all database operations on the low level. It uses a threadlocal variable to keep the current hibernate session and the transaction state. At the end of each UserClick/Servlet Response, the session must be closed by using DB.getInstance().close(), before it can be returned into tomcat's threadpool!

Controllers should only use the beginTransaction(), commit() and some helper functions to reload an entry from disk if the associated session has been closed (e.g. transactions which would last several userclicks)

Manager classes should encapsulate business logic and thus be the only ones that use the find/save/update methods of the DB class

The Syncer allows cluster-wide synchronization on a given OlatResourceable. That means that for each given OlatResourceable, at most one thread of all JVMs executes the „execute“ method of the provided SyncerCallback or SyncerExecutor concurrently.

public <T> T doInSync(OLATResourceable ores, SyncerCallback<T> action);

if you don't need a return object, then use the SyncerExecutor instead

public void doInSync(OLATResourceable ores, SyncerExecutor action);

An OlatResourceable is considered to be equal to another when both its type (a string) and its Id (a Long) are equal.

PS: In the current Syncer implementation the DB transaction is committed before doInSync returns. That means that you will have multiple commits during the handling of a request

PPS: In the current Syncer implementation doing so-called nested-doInSyncs is not allowed. Nested doInSync is when you are within a doInSync and call doInSync again. This will throw an Exception. The reason for not allowing this is to avoid potential, distributed deadlocks.

public void doInSync(OLATResourceable ores, SyncerExecutor e) {
	synchronized (DerivedStringSyncer.getInstance().getSynchLockFor(ores)) {
		e.execute();
	}
}

public void doInSync(OLATResourceable ores, SyncerExecutor e) {
	String asset = OresHelper.createStringRepresenting(ores, null);
	synchronized(DerivedStringSyncer.getInstance().getSynchLockFor(ores)){
		DBFactory.getInstance().beginTransaction();
		// acquire a db lock with select for update which blocks other
 		// db select for updates on the same record 
		// until the transaction is committed or rollbacked
		PessimisticLockManager.getInstance().findOrPersistPLock(asset);
		e.execute();
		// now release the lock - only if previously no other
 		// transaction was spawned.
		// commits only if the beginTransaction above was the first
 		// nested - otherwise the commit reaching level floor will 
		// actually commit it.
		// the transaction bracket is opened and closed here so that
 		// also non-db synchronized actions such as file system 
		// operation can be safely synced.
		DBFactory.getInstance().commit();
	}
}

This is the replacement for the old LockManager class .

It allows to obtain a lock on a given OlatResourceable.

Both non-persistent and persistent Locks can be aquired.

A non-persistent Lock is cleared when either the JVM crashes or (more often hopefully ;)) when the user that is the owner of a Lock logs off or when the controller that technically holds the lock releases its lock, e.g. in the dispose() method. Non-persistent locks are used for GUI-Locking.

A persistent Lock survives JVM startup/shutdowns and is used to protect access to resources where an explicit release of the lock is needed. (e.g. when editing a QTI document)

Try to avoid persistent locks in favor of non-persistent locks.

The Cacher is a hierachical cache structure to cache data

If, for example, you would like to obtain a cache per identity per course (to e.g. be able to cache the assessment data for the user), then you must build the hierarchy as depicted above. The CourseEnvironment creates an AssessmentManager instance per Course which then obtains a CacheWrapper from the Cacher, and e.g. will create child CacheWrappers for its Course and request CacheWrappers for each identity of this course (normally lazily, that is only when data needs to be read). For each level the ehcache configuration is read from the olatcoreconfig.xml (e.g. a „Course“ entry is then applied to all child CacheWrappers which are created with an OLATResourceable which is of type „Course“)

Configuration parameters are:

See also the Hints and cookbook section.

The hierarchy is only used for namespacing reasons. To e.g. obtain a cache for a certain user in a certain course, it is recommended that the responsible manager class holds a root-CacheWrapper and then for each course it creates a child CacheWrapper which in turn is used to create a CacheWrapper per user by using the appropriate method on the course CacheWrapper. The actual cached data for an identity resides in the CacheWrapper obtained for the Identity.

PS: Make sure to not store objects retrieved from the Cacher in instance variables. Otherwise an object might have been replaced with a newer version in the Cacher yet you don't notice as you're still holding the old object. Also it would violate the idea that the Cacher can control how many objects are kept in memory (memory management)

PPS: Note that there is currently an issue (OLAT-4424) where you can potentially run into a nested doInSync exception due to a cached object having to be reloaded

The EventBus is used to broadcast messages which normally affect more than one user.

It offers channels (identified by a OLATResourceable) to separate between different topics of interests. Code can subscribe/register and unsubscribe/deregister.

If your code subscribes to the channel, it is also responsible to unsubscribe at the end of your object's lifecycle (e.g. in the dispose() method of your controller).

The event bus has a topic or publish/subscribe architecture – that is the sender of a message does not know

The recepient on the other side should:

Next is a list of things to avoid in coding, please add more to it.

We describe a few tips, hints, and a kind-of-a-cookbook for the four tools explained in the previous chapter.

private static CacheWrapper assessmentMainCache = CoordinatorManager.getCoordinator().getCacher().getOrCreateCache(NewCachePersistingAssessmentManager.class, null);

private NewCachePersistingAssessmentManager(ICourse course) {
  this.course = course;
  courseCache = assessmentMainCache.getOrCreateChildCacheWrapper(course);
}

private CacheWrapper getCacheWrapperFor(Identity identity) {
  OLATResourceable ores = OresHelper.createOLATResourceableInstanceWithoutCheck("Identity", identity.getKey());
  CacheWrapper cw = courseCache.getOrCreateChildCacheWrapper(ores);
  return cw;
}

<bean class="org.olat.core.util.cache.n.impl.cluster.ClusterCacher" ...>
...
<property name="rootConfig">
 <bean class="org.olat.core.util.cache.n.CacheConfig">
   <property name="childrenConfig"><map>
    <entry key="org.olat.course.assessment.NewCachePersistingAssessmentManager">
     <bean class="org.olat.core.util.cache.n.CacheConfig">
	<property name="timeToLive" value="1" />
	<property name="timeToIdle" value="1" />
	<property name="maxElementsInMemory" value="1" />	
	<property name="childrenConfig"><map>
	 <entry key="CourseModule">
	  <bean class="org.olat.core.util.cache.n.CacheConfig">				   
	  <property name="childrenConfig"><map>
	    <entry key="Identity">
	     <bean class="org.olat.core.util.cache.n.CacheConfig">
	      <property name="timeToLive" value="0" />
		<property name="timeToIdle" value="60" />
		<property name="maxElementsInMemory" value="1000" />
	     </bean>
    	    </entry>
	   </map></property>
	</bean>
...

Whenever you have a little text fragment that you want to display on screen you can use the TextComponent .

The following features are supported:

When the text (raw or i18n) and CSS class changed on an instantiated object using the appropriate setter method the text element will be redrawn on screen. This means that when you put a TextComponent in a VelocityContainer , you can change the displayed text without making the container dirty. Only the text component itself will be redrawn. This has many advantages when building a commplex GUI and you don't want to redraw everything just because a litte text element has changed.

Usage examples can be found in the GuiDemoLinksController . To create a TextComponent object, use the TextFactory . There are two methods: