Overview

Elephant is an application framework based on components. Web Application Developers would not start from scratch, instead will implement standard interfaces. Some of the great advantages of using Elephant are the existing set of components and site administration. Elephant users can expand the site at will, by adding childs to existing pages and selecting whether these childs my or not show in navigators.

Offerings for developers

Take a look at the Elephant building structure. By creating a new component, you are reusing a lot of already working code. Your application will integrate smoothly into already existing web sites, using standard components as: Portal Mailing System, Automated Mailing Lists, Web Search System, Page Scripting, Macro Scripting, etc.

Offerings for web masters and/or final users

Web masters will enjoy using the existing set of components. It gives them full power on web site appearence while makes quite easy creating new pages and their content. Navigation issues are fully supported by Elephant configuration files, with attributes like: Show In Navigators, Tell Robots NOT_TO_INDEX / NOT_TO_FOLLOW, Supported Languages, Internationalized Names, etc.

Page's content is also greatly assisted. When no component is defined, Elephant's DefaultElement takes place. DefaultElement implements what is required to create page content. Repository for images and documents, easy syntax (no HTML, though is permited), version control, author tracking, multi-language support, etc.

One of the magic things that make Elephant easy to use and powerful is the structure is build on. When Elephant takes control you are always in a Context . As for creating web pages, you'll need to understand what a context is and its relation with other contexts.

A context is a web page. We didn't called web page because it seemed too simple for such a marvellous creature, but is nothing more than a web page. Anyway, as to continue making things complicated where they should be easy, we will call this web page a context.

Construction

Context builds up with two different kinds of elements. The actual elements and the layout elements. Despite their names, they respond to a very usual situation. You know how your site should look and don't want to repeat the design for each page. These elements are the layout elements. They are defined at top level, in site's home, and inherited for lower levels.

The image shows what the layout elements are, surrounding the actual content, which is not more than the actual element mentioned above.

By default, the actual element is HTML content, text, written with the special Elephant syntax.

Pages

Elephant sites allow creating as many contexts as you might require, remember a context is equivalent to a page. There is no other limit than the available space and your imagination. Creating pages involve thinking where you want to contruct them. To understand this you might think of your site as a tree. The trunk is the home page. First branches will be home its children and so on. Your tree can have many branches, Elephant will take care to make easy the navigation among them.

Each context has several attributes that define its behaviour.

When you want to show an image in a page, you need first to upload the image file. Where this file goes to it's called repository. Each context has its own repository. So, you have as many repositories as web pages. Each one with its own structure and content.

Elephant maintains different caches to increase performance.

• Site values in site.xml.
• Label bundles.
• Contexts map.
• Social images map.

The Tools menu has an option that allows to reset these caches. Also forces the sitemap generation. Use with caution.

Elephant provides a DefaultElement with edition capabilities. The editor uses the Wiki syntax to ensure a correct HTML result. Also, the wiki syntax, used as is with no classes and styles, is compliant with the email templates. Write once, use everywhere.

The elements at play

This graphic shows the elements that provide content for a web page or an email. By changing the templates root, the marker will generate different layouts. The wiki syntax ensures that the content fits into these templates.

See a complete reference of the available Macros

Templates' root

As noticed above, email templates are not the same than web templates. The main reason is because for web templates we have a complete framework whereas email templates have only a subset. Email clients, or readers, limit the number of CSS and JavaScript features available, making emails a complete different world.

To understand how Elephant deals with those differences, see the button template for an email and for the web.

Email button

<table border="0" cellpadding="0" cellspacing="0">
  <tr>
    <td align="center" bgcolor="${bgcolor}" style="-moz-border-radius:4px;-webkit-border-radius:4px;border-radius:4px;">
      <a href="${link}" style="padding:10px 20px;display:block;text-decoration:none;border:0;font-weight:bold;font-size:15px;color:${color};background:${bgcolor};border:1px solid ${bgcolor};-moz-border-radius:4px;-webkit-border-radius:4px;border-radius:4px;line-height:17px;" class="button_link">
        ${text}
      </a>
    </td>
  </tr>
</table>

Web button

<a href="${link}" class="ui primary button">
  ${text}
</a>

Elephant renders its contexts using layouts.

Template layout is the new default layout for new Elephant versions. In order to make template layout compliant with current table layout versions, template layout makes use of different CSS files.

To activate templates for the whole site, use the template element under layout on the root context. For local templates, those applying to the context where are defined, use the local-template element.

Typical configuration is:

context.xml

<?xml version="1.0" encoding="ISO-8859-1"?>

<elephant-context lang="_en">
  <i18n>
    <name>
      <_en>Home</_en>
    </name>
  </i18n>
  <layout>
    <local-template name="landing"/>
    <template name="web"/>
  </layout>
</elephant-context>

webTemplate.html

<#include "header.html"/>

<div class="webBody" style="width:100%;background:#fff;">
  <div style="width:1000px;margin:auto;">
    <table style="width:100%">
      <tr style="vertical-align:top;">
        <#if nav.hasOptions(2,1,true)>
          <td style="width:25%;padding-top:15px;padding-right:15px;">
            ${nav.drawOptions(false,2,1,true)}
          </td>
        
        <td style="padding-top:15px;">
          <#if traversal>${nav.drawTraversal(true)}
          ${body.startConstruction()}
          <#if traversal>${nav.drawTraversal(false)}
          <#if printVersion??>${printVersion}
          <#if fileVersion??>${fileVersion.render()}
        </td>
      </tr>
    </table>
  </div>
</div>

<#include "footer.html"/>

header.html

<div class="header">
  <div style="width:1000px;margin:auto;">
    <table cellpadding="0" cellspacing="0" style="width:100%;height:40px;">
      <tr style="vertical-align:bottom;">
        <td>
          <a href="${constructor.rootWebPath}">
            <img src="${constructor.rootWebPath}/_internal/repository/logo.png"/>
          </a>
        </td>
        <td>
          ${nav.drawTabulator(1)}
        </td>
      </tr>
    </table>
  </div>
</div>
<div style="width:100%;margin-top:43px;">
  <div style="width:1000px;margin:auto;">
    ${nav.drawLocation()}
  </div>
</div>

footer.html

<div class="footer">
  <div style="width:1000px;margin:auto;">
    <table cellpadding="5">
      <tr style="vertical-align:top;">
        <td>${webmap.draw(3)}</td>
        <td width="20%"><#include "credentials.html"/></td>
      </tr>
    </table>
  </div>  
</div>

landingTemplate.html

<#include "header.html"/>

${body.startConstruction()}

<#include "footer.html"/>

Table layout was the out-of-the-box configured layout from the beginning. Table layout creates an HTML table as the main container. Uses context/_internal/context.xml files to read the configuration. Tipical web root configuration is:

<?xml version="1.0" encoding="ISO-8859-1"?>

<elephant-context lang="_en">
  <i18n>
    <name>
      <_en>Home</_en>
    </name>
  </i18n>
  <layout>
    <element id="20060126192226678" align="top" type="default-container" container="true">
      <attrib name="type" value="header"/>
      <element id="20060126192226654" align="top" type="default-element">
      </element>
      <element id="20060126192226679" align="left" type="default-navigator">
        <attrib name="type" value="tabulator"/>
        <attrib name="level" value="1"/>
      </element>
    </element>
    <element id="20060126192226680" align="top" type="default-container" container="true">
      <attrib name="type" value="locator"/>
      <element id="20060126192226681" align="left" type="default-navigator">
        <attrib name="type" value="location"/>
      </element>
    </element>
    <element id="20060126192226682" align="left" type="default-container" container="true">
      <attrib name="type" value="container"/>
      <attrib name="width" value="180px"/>
      <element id="20060126192226683" align="top" type="default-navigator">
        <attrib name="type" value="options"/>
        <attrib name="level" value="2"/>
        <attrib name="children" value="2"/>
        <attrib name="show-current" value="true"/>
      </element>
    </element>
    <element id="20060126192226685" align="bottom" type="default-container" container="true">
      <attrib name="type" value="footer"/>
      <element id="20060126192226684" align="top" type="default-element">
        <attrib name="type" value="footer-inside"/>
      </element>
    </element>
  </layout>
</elephant-context>

Elephant uses ElephantMarker as the template parser. It's based on FreeMarker and adds the necessary configuration to operate with the Elephant IConstructor.

ElephantMarker uses a template root to locate templates. The template root is configured in the site.xml file.

Templates are used at different levels to generate the final HTML, CSS and JavaScript.

Naming templates

The conventional way ElephantMarker uses to locate a template is by searching [templates_root]/[context]/[name]Template.html. The context variable is the child explained is the above table and helps to differentiate templates usage. Name is the actual template name and the marker appends Template.html.

This convention allows the overriding system Overriding templates .

To understand the override mechanism used by the Elephant library you need to understand how templates are found. By default, ElephantMarker searches templates in /WEB-INF/elephant/[templates_root]/[context]/[name]Template.html, being context and name variables. templates_root is defined in /elephant/conf/site.xml configuration file.

Provided the templates_root is templates-semantic, a context and a name, Elephant will first search /WEB-INF/elephant/templates-semantic/site/[context]/[name]Template.html and, if no file existed, in /WEB-INF/elephant/templates-semantic/[context]/[name]Template.html.

This is a list of commonly used content templates. Does not reflect the actual number of templates available for layouts, entities and email senders.

The banner templates use a JSON source as banner data. Its form is:

• name
• minHeight
• banners (array of:)
• imageLink
• background
• color
• header
• meta
• description
• action
• link
• subaction
• sublink

The most common way to use it would be the marker-jason macro {@marker-json:tmpl-root:template:repository-file}, where tmpl-root is files, template can be bannerImage or bannerCard, and repository-file would be the location of the JSON file.

In the example will be using the banners.json file, located at this context's repository.

With {@marker-json:files:bannerImage:*/banners.json} you get:

With {@marker-json:files:bannerCard:*/banners.json} you get:

Some header

Sub header

Lorem Ipsum is simply dummy text of the printing and typesetting industry...

Visit... Or visit...

Some other header

Some header support

Lorem Ipsum is simply dummy text of the printing and typesetting industry...

Visit...

JSON file

{
  "name" : "slider",
  "minHeight" : "400px",
  "banners" : [
    {
      "imageLink" : "banners/_internal/repository/elementals.jpg",
      "background" : "#00000066",
      "color" : "#fff",
      "header" : "Some header",
      "meta" : "Sub header",
      "description" : "Lorem Ipsum is simply dummy text of the printing and typesetting industry...",
      "action" : "Visit...",
      "link" : "#",
      "subaction" : "Or visit...",
      "sublink" : "#"
    },
    {
      "imageLink" : "banners/_internal/repository/emotion-ocean.jpg",
      "background" : "#ffffff66",
      "color" : "#000",
      "header" : "Some other header",
      "meta" : "Some header support",
      "description" : "Lorem Ipsum is simply dummy text of the printing and typesetting industry...",
      "action" : "Visit...",
      "link" : "#"
    }
  ]
} 

Elephant Users is based on the BrightSide Contacts module. A user is always a contact.

Contacts becoming users

Any contact can be transformed into a user, by giving a connector called Email. Users with this connector can authenticate into the User area and manage their own profile.

If enabled, the User area can also admit new sign-ups. The sign-up process validates the user email. Registered users get the Social Group Guest, with no permissions attached. Administrators receive an email and push notification with the new user name and email.

User's permissions are controlled by the Elephant Security System, explained in Security .

ComplexName property gives the choice of treating users with a chain of formality. The API also offers a guessing option, using the European way of treatment, excluding titles and gender.

Complex name properties

Complex name return

ComplexName will always return a value, despite the property being empty.

In Elephant nomenclature, a user is a contact with an email and able to sign in. Users can also sign up, if the website allows it (has a sign up context)

Automated relations

Elephant gives the user the opportunity to enrich his profile, while getting more permissions. Any user can send a request for a new relation, and acquire permissions once validated. There are some limitations, though, to make sure a single user has not contradictory roles (ex. student and docent)

• Professionals and Docents can not be Students. This could clash regarding challenges.
• Likewise, Students can only be students.

Profile completion

When configured, the profile completion gives the user some tips about completing the profile. Tips may vary, depending on the relation type and what has already been completed.

Using user's profile, any user can add relations to existing companies or learning centers. Relations created by users are moderated, administrators must validate all proposed relations.

When a user has no relations, it is offered several options, depending on the existence of companies or learning centers. If none of them are in your contacts database, nothing will be offered.

The differences among these relations, are:

After a relation request has been sent, the profile will update the status.

Notifications

Activity catchers are mainly related to user activity or participation. Their purpose is to isolate modules from contacts, without losing the ability to react on changes.

Catchers are lists of activities. Activities can be entity participations. Each activity use to contain a user participation. For instance, a user will participate in an issue if has a role within the issue, but not if just commented or participates in issue's dossier.

Assistants

Assistants are users that do not actually participate in an entity, but have entity permissions to assist. An example of assistants is the add by entity combobox. Deep assistants are those who do not assist directly in the related entity, but do indirectly in a parent oriented hierarchy.

Last activity centered

The Elephant system also provides last activity catchers. The activity source might be known or at first unknown. Known sources are data collected from actual entities. The unknown source is basically the log system, in which user activities are registered.

The Agreements API help web administrators to deal with legal issues regarding data protection, terms and conditions.

Why an agreement API?

You may need to warn the user about things like:

• What you do with the collected data.
• The terms and conditions of the offered services.
• Fine-grain previous points by certain actions.

The Agreements API provides a lightweight method to store when a user accepts what the agreement proposes. In order to achieve this, there are some restrictions you should be aware of:

• Each agreement has a single use. Once a user accepts, the agreement can't be deleted.
• Modifying the text, when users already accepted the agreement, it's a bad practice. Currently, you are able to change the text, but in the future this will change, forcing a read-only mode, or deleting all acceptances.
• If you intend to create specific agreements for temporal events, take in mind the single use restriction. Make the text as generic as possible. The benefits are, fewer interactions user/agreement, and a full memory of the acceptance.

How does it work?

First of all, you create an agreement. The main fields are:

What final users will see?

When the required signature forbids sending notifications, a Pending signature notification will be sent. The user will be able to Accept or Decline the agreement from the notification email.

When the required signature forbids operating, the user will be redirected to the agreement, expecting to Accept or Decline the agreement.

The agreement flow

Notifications

Modules chose whether to treat users as Observers or Participants.

The generic rule to follow explains itself better in terms of participation. When a user participates in a module, the participation will prevail to the not signed status.

Publication category subscriptors are not considered participants, but observers. In this case, not signed prevails.

Module actions

Elephant Calendars are a full set of events, generated from application entities. Unlike Activity, calendars also contain future events and a relevant subset of the activity.

Calendars intention is to gather, in a temporal element, information about entities, display a summary and a link to the entity.

Calendar content

Calendars can be configured to show different content, and related-content. To understand what to expect from a Calendar, depending on the context where it's shown, see the tables below:

Calendar entities

Each Non-related Calendar can be configured to display certain entities. The entities that can be configured are:

Calendar popups

Calendar popups are user conscious, showing only what is allowed to see by the target user. If allowed, users can see full detail in the user area, or the corresponding context if configured. For admins, when appropriate, also a link to the application.

Standard calendars provided

Some calendars are provided out-of-the-box, as part of the application functionality.

Calendar for admins

Admins have full access to calendar events using BaaS -> Session -> Calendar.

Elephant Colors API provides some useful methods for manipulating colors. The main goal, though, is finding the adequate font color, based on a solid background. The API can be accessed within templates using the helper object helper.color([name|hexvalue|rgb[a]()]). This function returns a Color object with these methods:

Default palette

This palette is provided as color choosing helper. Any other color can be used with the Elephant Colors API. The palette uses the API to choose the adequate font color using the Color object:

// assign color using color = helper.color('name or hexvalue or rgb[a]()')

<div style="background-color:${color.css()};color:${color.font().css()}">
  ${color_name} (${color.css()})
</div>

Elephant provides a cookie tracking mechanism to allow / decline types of cookies. The Cookie Management's goal is the ability to work in Elephant templates.

API calls in templates

helper.cookies.anyUnset()

helper.cookies.unset(type)

helper.cookies.allow(type)

helper.cookies.decline(type)

helper.cookies.createPost(type, accept)

helper.cookies.createFormAction()

Simple management for analytics cookies

This example will show how to use the cookie tracking mechanism to allow or decline Google Analytics.

First, check if "track" type of cookies is unset and provide a user selection:

<#if helper.cookies.unset("track")>
  Would you allow Google Analytics?
  <a onclick='${helper.cookies.createPost("track", true)}'>Allow analytics</a>
  <a onclick='${helper.cookies.createPost("track", false)}'>Forbid analytics</a>
< /#if>

<#if helper.cookies.allow("track")>
  #your Analytics code here
< /#if>

Using the default Elephant management for cookies

Elephant also provides a cookie management easy to activate. By default remains inactive due no configured cookies. To use the Elephant management create the file cookie-context.properties in /WEB-INF/elephant/conf folder. Edit in BaaS -> Tools -> Files -> Configuration -> Properties editor and write this:

track=lTrackCookie

This line will activate de track cookie, explained in the labels key lTrackCookie. Now, just put the tracking code like this:

<#if helper.cookies.allow("track")>
  // the tracking code, ex. Google Analytics
< /#if>

To control more kind of cookies, simply add more lines to the cookie-context.properties, being the key the cookies' type. For single language sites, is possible to explain the type directly in this file. Otherwise, use a label key and add the corresponding values to the labels-site[_lang] files (see BaaS -> Tools -> Files -> Configuration -> Resources)

Authenticated users will be able to modify their cookie preferences in the Session menu.

Agnostic tags

You can use any HTML tag with EWiki, by simply enclosing the tag in brackets []. Also, you can convert any HTML tag to a Text container by adding -text to tag's name.

Containers and Text containers

EWiki defines a Container as the content wrapped between [tag] and [/tag]. Containers are similar to normal HTML containers, with no especial treatment for new lines and empty lines.

A Text container, on the other hand, is the content wrapped between [tag-text] and [/tag-text]. Text containers treat new lines as line feeds, and empty lines as the beginning of a new paragraph.

Mixed content

The directives related to changing the interpreter mode are no longer required. HTML can be embedded within wiki causing no extra formatting, except for text containers. Java code and XML can be included as blocks or inline using enclosing java and xml tags.

Easy escaping characters

Any character can be escaped using the backslash. The exception are macro parameters, where compiler especial characters should be transformed to HTML entities.

To the EWiki compiler, tags are simple names that will be transformed into the HTML format. A [div] will be a <div>, without paying any further attention at the name div.

Parameters

Parameters differ from HTML. They are enclosed within parenthesis, separated by commas, using a colon to divide the attribute from its value. In the simple form, [div(font-weight:bold)] will be as HTML <div style="font-weight:bold">. At this point, doesn't seem to help much, but let's consider this: [div(font-weight:bold,margin:10px,class=supersized)], where the HTML will be <div style="font-weight:bold;margin:10px" class="supersized")>. First thing you may notice is that the compiler detected class as a separated attribute. Also, it's not necessary to create a style, nor include quotes.

Containers

As in HTML, EWiki tags are containers. You can add content within the container opening tag, and the closing tag.

EWiki introduces a major difference here, allowing any container to easily write text. By adding the suffix -text, EWiki containers create paragraphs by using simple line feeds. By default, the root container is a text container.

[div]
Hello

world
[/div]

[div-text]

Hello

world
[/div-text]

EWiki macros are resolved at compile time, when wiki is transformed to HTML. An expanded macro will not change, despite there are changes in the macro, until you save/compile the wiki content.

EWiki macros are self-contained in a single file, and the compiler finds and expands them.

An EWiki macro can have nested content, including more macros, or single line.

Macro parameters

Macro parameters are enclosed in parentheses, must be named as name=value and comma separated. Values with special characters, like a comma, can be enclosed in double or single quotes.

EWiki provided macros

Actions

Cards

Containers

Grids

Images

Items

Labels

Lists

Messages

Stripes

Support

Tables

Text

Users

EWiki provided macros may help you to create rich content, like striped landing pages, documentation, encapsulation, ...

Headers

The macro header creates an HTML header with an optional icon and a sub header.

@w{header(icon=cog)}
This is a header
@w{subheader}...with a sub header.@w{/subheader}
@w{/header}

Headers can also change size.

@w{header(class=big,icon=cog)}
This is a header
@w{subheader}...with a sub header.@w{/subheader}
@w{/header}

Stripes

The macros stripe and textstripe create a container that will reach the left and right borders, and a nested container with the normal width. This ensures a full stripe of the desired color, occupying the container limits. For landing pages, horizontal limits are the browser width.

@w{stripe(color=RedGold)}
@w{header(icon=cog)}
This is a header
@w{subheader}...with a sub header.@w{/subheader}
@w{/header}
@w{/stripe}

@w{textstripe(color=RedGold)}
@w{header(icon=cog)}
This is a header
@w{subheader}...with a sub header.@w{/subheader}
@w{/header}
@w{/textstripe}

Messages

The message macro is a way to draw attention to specific content.

@w{message(class=info,icon=info,header=Informative message)}
This content can be any EWiki content.
@w{/message}

@w{message(class=warning,icon=warning,header=Warning message)}
This content can be any EWiki content.
@w{/message}

Cards

The cards and card macros create an encapsulated content, with an optional image.

@w{card(image=repository(/topcard.jpg))}
@w{content(header=Card header)}
This content can be any EWiki content.
@w{/content}
@w{/card}

Card header

This content can be any EWiki content.

Wrapping cards within the cards macro can control how cards will show in rows, the type of card, color and more. Check the cards macro definition.

Items

The items and item macros create an encapsulated content, with an optional image.

@w{items}
@w{item(imgclass=tiny,image=repository(/topcard.jpg))}
@w{content(header=Card header)}
This content can be any EWiki content.
@w{/content}
@w{/item}
@w{/items}

Card header

This content can be any EWiki content.

Wrapping items within the items macro can control the type of item, color and more. Check the items macro definition.

Files based are components using the private part of Files from BrightSide Attachments. Each uses a specific root and makes the content available to specific roles or users, depending on functionality.

Current components are [ Deliverables, Documentation ] .

The Deliverables component aims to facilitate publishing entity deliverables. The roles allowing uploads and downloads can be controlled using Concept permissions . The show permissions grant users to download. The action permissions grant users to upload.

The administration form is quite forward and responds to user roles.

The goal of this component is to allow specific roles to require documentation to specific users.

Documentation definition

Before requiring documentation, a definition about this documentation must be made. The definition fields are:

Especial cases

• The administrators are allowed to reject a documentation, even if it was already accepted.
• The upload button appears even if the file limit is met. The purpose is to allow overriding the existing file. The system controls whether the file is an override or an addition.

The flow

Documentation fulfillment is a conversation between a requester and a requested, both registered users. The status of pending actions will appear in both users areas, with an easy-to-follow link.

Empty documentation form. The request action must be initiated by users with specific roles, depending on the associated entity.

The user with the right roles starts a request and the status changes to pending to upload. Only the requested user will be able to see the form and upload documents.

The documentation is uploaded and pending validation. Only the requester or administrators can validate or deny the documentation.

Denied documentation with a reason message.

Validated documentation.

The Elephant library has the ability to create a help context for each page, also called a context in Elephant nomenclature.

Help contexts are normal contexts that follow some rules. First, they have a single root, called help context root, second, they pair the path of the context that needs a help context and third, they have content.

The help context root is defined in /WEB-INF/elephant/conf/help-context.properties file, using root=[help context path] as an absolute path starting with / as the web root.

Learn by example

Suppose root=/docs/platform in the configuration file.

How does show a help context

As seen before, in case the help context exists and has content, an will appear at bottom left of the screen. By clicking this icon the web visitor will get the help content as a modal popup.

Best practices

When creating the root for help contexts, is a good idea to protect it for casual visitors. Since some contexts will have no content, has to avoid the help icon to appear, the help root is not visitor friendly. The usual restricting role should be sysinfo:list, since points to web content administrators.

Elephant internationalization project aims to create an easy to maintain translation base.

The API

Hard-coded variations

Elephant i18n accepts adding variations to a single key. Those variations are singular and empty when the key contains a number formatting symbol like %d and %f, and their own variations.

They are applied when the i_.get('text', count) is called, count will replace the formatting symbol and a variation will be selected depending on count value. For > 1 the basic key, for =1 the singular key and for =0 the empty key.

Handling gender

Handling gender with i18n tools has always been a hard topic and is a matter of which language you take as reference when writing keys. Let's suppose you are the developer, and you are using English as the main language (Elephant i18n default). Now, you write this in your application:

i_.get("%d selected", images.size())

Some languages apply gender to adjectives, which means that selected will be different depending on what is selected. For example, in Catalan images would be seleccionades and files seleccionats. Gender might be different in other languages, and the API makes no hard-coded assumptions.

Elephant i18n approach to solve this problem using key discriminators. Key discriminators generate a different key, but do not show when rendering the translation. A discriminator is a sequence of lowercase letters, up to three, prefixed with the exclamation character. For example !f.

Elephant translations use English as the main key generator and Catalan as the gender reference. An example to solve the previous example would be:

i_.get("%d selected!f", images.size())
i_.get("%d selected!m", files.size())

In this example, English will show the same message (n selected) and will generate two different keys, allowing translators to apply gender to their translations. Elephant convention uses !f for female and !m for male.

Another approach would be using the discriminator to describe the noun, for example !img for images and !fil for files. This solution involves a more developed set of keys and arises the question about why not using the noun in the message (%d selected images).

Notice that the Translator API showing other language translations, tends to facilitate recognizing the pattern. Anyway, a full knowledge of how many languages and languages themselves, would be necessary to fully understand, and maybe solve, the problem. Discriminators are just a none hard-coded help. And there is always the try/error approach.

Translators

Elephant I18n recognizes translators as a specific actor. A translator can be assigned to a single language, to a partial set of languages, or to the whole site set.

Elephant I18n also provides an editable translation for the whole site set of languages, when adding entries.

Migration

The new API features a compatibility wrapper to allow a slower adoption. The compatibility wrapper does not solve all cases, particularly those scarcely in use.

The main difference between both APIs, compatibility and I18n, is the key treatment. I18n use keys only internally. In code you will only see readable text.

Compatibility table

By key

Even though this API aims to create a more readable code, still exists some hardcoded keys that need translation. Example of those are languages codes and Java enums. If everything were to be converted to natural language, the relation with codes will be broken. The ByKey extension allows to keep one to one relation between coded keys and natural language. Also, enforces Elephant I18N by creating the natural language related to the key used by this API.

I18n lanes

Elephant Importer API provides a way of loading data into modules implementing ImporterProvider.

Importers can add to the existing data or fully replace it. The importer front-end shows this option as Full import.

Provider sources

By default, data sources are CSV files uploaded into a provider. The API deals with the usual CSV formats, including differences among operating systems.

Currently accepted data sources are:

Sources must include a first row with headers. The importer will use those headers to map columns to actual fields.

Providers

Alliance Contact Provider

Imports data into Alliance Contacts. The accepted fields are:

Alliance Project Provider

Imports data into Alliance Projects. The accepted fields are:

Alliance Participation Provider

Imports data into Alliance Participations. The accepted fields are:

Alliance Tag Provider

Imports data into wide-application Tags API. The accepted fields are:

Elephant provides the Indicator API as a way to generate statistics from entities. The main goal of the API is to facilitate the generation among modules, on separated DBs.

Indicators are usually stored using a separated convenience API. Examples of using indicators are the Ranking and Matching APIs. Both take indicators values and store them where needed, independently of the source of the stored data.

Main goals

• Inheritance from AbstractIndicator, concentrating efforts on providing data.
• Discovering indicator classes via annotations.
• Isolated from the storage mechanism, both when generating or reading.
• Ability to find indicator values with a sound syntax, based on the storage APIs.
• Statistics.

Indicator composition

Since indicators are stored using separated APIs, the indicator may vary in its composition. For example, the Ranking API relates to sets of single entities, while the Matching API does with two entities. Provided that storage depends on others and Indicator API needs read access, the API imposes some requirements.

• Entities should be stored in the standard Elephant mechanism.
• Table names and entity names must correspond.

The reading mechanism

Since indicators solely generate and provide data, seems that being able to read this data on a separate process is far off its possibilities.

The reading mechanism comes in help and is able to provide indicator values for statistic purposes. To achieve this goal, indicators find storage classes and provide an specific syntax for reading its values at single, multiple or formulated basis.

Reading syntax

The form taken by readIndicator parameter is:

JPAEntityClass:IndicatorClass:entityPath[:relatedPath]:indicator

Wildcards

Discovering indicators

To understand how reading syntax helps locating values, this image shows the process of getting values.

Optimizations

Indicators are created from within modules and using JPA contexts. The results are stored at module convenience in order to be accessible for database queries. The Ranking API and the Matching API assist saving results in specialized tables. This would be the standard, and preferred, method.

Before diving into possible process optimizations, let's see some numbers.

Quantifying results

A ranking set of indicators will create (indicators + final_ranking) * entities tuples. For instance, if you have 500 entities and need 10 indicators to calculate the ranking value, this will create (10 + 1) * 500, 5,500 tuples. Not so bad.

A matching set of indicators will create (indicators + final_matching) * entities * related_entities tuples. Things have slightly changed since there is another factor: the related or entities to match with. The matched entities are usually contacts. Let's do the same example as above, saying that we have 1,000 contacts to match with. Applying the factor to the previous result give us the amount of 5,500,000 tuples. Quite impressive, isn't?

Three optimization approaches

Spare zeros is a first approach to optimize the results. The API does not save zero or near to zero values. The impact of this optimization highly depends on the related selection of the second approach, but is at least significant for non relevant indicators.

Fine selection approach affects both entities and related entities. It's difficult to implement since implies some kind of guessing which pairs are prone to match. The impact of this optimization is high because supposedly eliminates zeros and, more important, reduces the number of database reads.

Bulk data might be the more effective approach. Makes an initial selection and does de insertions as a pre-process. When doing so, the indicator does not have to load entities separately, knows the result from the read data.

Formulas are mainly composed by variables, constants, operators and functions. See Variables for a full list of available ranking and matching variables.

Elephant Indicator API also adds some functions to facilitate the formula edition.

Using weighted values

Since variables return absolute values, being or not related to a second entity, the result treatment gets complicated. To palliate this, the weighted functions provide a more easy input.

weighted(value, meaning, weight)

Returns a weighted value based on:

• value being in most cases the variable.
• meaning the max number allowed for value, representing until which value has a meaning.
• weight being the max result after applying the actual weight.

reverseWeighted(value, meaning, weight)

Returns a weighted complementary value based on the same parameters that weighted.

Math functions

You can also use math functions to create your own calculations. Math functions are prefixed with Math, for example Math.floor(2.3) will return the parameter floor.

Variables are used inside formulas to create the final ranking or matching. Descriptions refer to current entity as the entity that's being processed and to self as the related entity for matching, usually a contact, therefore creating the self point of view.

Variables are used in Formulas .

Elephant renders macros each time a page is requested. Macros start with {@ special characters and expand into text or HTML code. Macros can even include content from a file, HTML page or JSP page. In order to understand what macros are for see what current macros do:

• Core
• Navigational
• Modules
• Documentation
• Macro summary

Macros can be nested, but take in mind that macros are written inline, in order to allow content inclusions. Thus, only macros that resolve to a string could be nested. Ex.

{@equals:{@user:id}:admin:Administering:Browsing}

To escape the : character prepend a slash, like /:.

Next generation

The next generation of macros provide a great number of features, aiming to easy-of-use customization. The main goals are:

• Order agnostic parameters. Parameters can be specified by name, in any order.
• Significant decrement of macro names. Using the order agnostic parameters, a single macro can offer more options.
• Easy escaping characters. Escape values enclose it in brackets, ex. name=[values] or [values].
• Single parser, multiple processors. Relaxes complexity on macro processors, by parsing parameter tuples.
• Improved fail detection. Parser detects macro existence before fully interpreting the content.
• Better backward compatibility. While using named parameters, macro changes won't break previous code.
• Error feedback. None interpretable macros will be rendered in red and failure will be logged in the system.
• Empty result default. Empty results can show a value using the system-wide parameter void.
• Fully nested macros. Macros can be nested, in order to provide values, macro names or the empty default.

Next generation macros are expressed as @{macro_name}.

Macros with readers, how does it work?

The easiest way to read a file is store it in context's repository and access it with */file. The * will expand into rendering context repository. For example:

{@marker-xml:xml:doc:*/doc.xml}

Reads doc.xml in current repository and passes its data to [Template_root]/xml/docTemplate.html to be formatted.

Reading properties

Properties are stored in props list in the same order they are stored on disc. You can iterate props with #list.

<#list props?keys as key>
   <#assign value=props[key]/>
   // do something with key and value
   ...
< /#list>

Reading XML

XML documents are stored in doc model. You can iterate the elements using dot syntax and iterate collections as you would usually do for any other data. The XML model is the FreeMarker NodeModel.

Reading JSON

JSON files are stored in json model. To access a root, use json.read("$.root"). If the root is a list, use json.list("$.root"). Once retrieved the root, you can iterate the elements using dot syntax and iterate collections as you would usually do for any other data. The JSON model is a subset of the JsonPath DocumentContext, optimized for templates usage.

The JSON books example

The data:

{
  "book": [
    {
      "title": "...",
      "author": "...",
      "excerpt": "...",
      "availability": "...",
      "link": "...",
      "filelink": "...",
      "imagelink": "...",
      "pages": 0
    },
    {
      ...
    },
    ...
  ]
}

The template (Semantic-UI):

<div class="ui divided items">
  <#list json.list("$.book") as book>
    <div class="item">
      <a class="ui tiny image" href="${book.link}">
        <img src="${book.imagelink}"/>
      </a>
      <div class="content">
        <a class="header" href="${book.link}">${book.title}</a>
        <div class="meta">
          ${book.author}
        </div>
        <div class="description">
          ${book.excerpt}
        </div>
        <div class="extra">
          ${book.availability}
          <#if book.filelink?has_content>
            <a target="_new" href="${book.filelink}">${book.pages}</a>
          < /#if>
        </div>
      </div>
    </div>
  < /#list>
</div>

Understanding what behavioural keywords are

Behavioural keywords stand for keywords controlling how information displays. The way behaviours will extend in future versions might be controlled in this section.

Understanding what navigational keywords and selection keywords mean

Navigational keywords end up as a list, colon separated, of keywords pointing to existing contexts. As starting point, path_to_contexts initializes to current context, that is, the web page where macro displays.

Here comes a brief description of what each keyword does and after some clear examples:

Navigation keywords move current selection from context to context.

Selection keywords actually return contexts, one or several. A zero results it's considered an error an macro will displays with m_error class, which defaults to red color and a warning image. Otherwise, macro expands into m_list class.

Learning by example

Current list of modules exposing macros.

• Attachments
• Calendar
• Contacts
• DAO
• Dossier
• Elephant
• Financials
• Publications
• Students