Structure

Structure

The directory structure of ADX looks like this:

Demo\
Examples\
Resources\
   |_ Dynamic\
   |_ Static\
   |_ Share\
Tests\
   |_ Cases\
   |_ Fixtures\
   |_ Units\
CHANGELOG.txt
Config.xml
Preview.png
Readme.md

NOTA:

• The rendering engine only use the Config.xml and the Resources directories, all other items are ignore.

Config.xml

The Config.xml is the main reference of the ADX.

It contains all meta-data, defines the public/private properties and the generation rules.

Also see: Config

Resources directory

It’s the main directory that will be used by the rendering engine.

It contains three main directories:

Dynamic directory

Because the content of surveys/questions are different, ADX must provide a dynamic content unless you want to obtain something like this over and over again:

Scary, isn’t it!

The Dynamic folder is where the magic happen!

It contains plain-text files (such as .txt, .xml, .html, .css, .js …) with AskiaScript.
All binary files (such as .swf, .png, .mov ….) must be place in the Static folder.

The rendering engine will load and cache the file content in the memory once it’s needed.
The access of dynamic files during the run-time, is done through the rendering engine which compiles the file and provides the output as string.

The AskiaScript used in dynamic files have a specific context:

• Context of the interview
• Context of the current question ADC only
• Context of the ADX properties (see: ADC Object in AskiaScript 2.0 and ADP Object in AskiaScript 2.0)

Examples of usage

• Generate HTML 5 inputs

File: TextNumber.html

{% If CurrentQuestion.Type = "numeric" Then %}
      <input type="number" name="{%=CurrentQuestion.InputName()%}" value="{%=CurrentQuestion.InputValue()%}" min="{%= CurrentQuestion.MinValue%}" max="{%= CurrentQuestion.MaxValue%}" />
{% Else If CurrentQuestion.Type = "open" Then %}
      <input type="text" name="{%=CurrentQuestion.InputName()%}" value="{%=CurrentQuestion.InputValue()%}" />
{% EndIf %}

Context: CurrentQuestion → Age_Of_Respondent

<input type="number" name="C1" value="" min="18" max="99" />

Context: CurrentQuestion → Comments

<input type="text" name="S1" value="" />

• Generate style according to the ADX Properties

File: Styles.css

.tickColor : {
    background : {%= CurrentADC.PropValue("tickColor").ToHexa() %}
}

Context: tickColor → #d4d4d4;

<style id="adx_name_styles_css" type="text/css">
.tickColor : {
    background : #d4d4d4;
}
</style>

Master page

ADP only

For ADPs, at least one master page is required under the Resources/Dynamic folder.

A master page is a regular HTML page with custom Askia tags and AskiaScript to make it dynamic.

Also see: Master page

Static directory

In opposition of the Dynamic directory, the static directory contains all files that doesn’t need to be dynamic.

All files in this folder, will be extract to the \Resources\[SurveyName]\[ADXName]\ paths in production environment.

Because we can use several instance of the ADCs in the same page, the rendering engine will load some resources (CSS, JS) only once for all instances.

Share directory

This is a special folder which contains all libraries and dependencies which could be used by several ADC’s. All files in this folder, will be extracted to the \Resources\[SurveyName]\ paths in the production environment. All files in this folder, will be use as it is, so it could not embed AskiaScript code on it.

Because the Share files could be used by several ADCs, the rendering engine will load the files only once for all ADCs in the same page. The rendering engine will assume that Share files already manage their back-compatibility, so it will use the latest version of the files.

To determine the latest version of Share files the rendering engine will use the date information of the ADC.

Examples of content: jQuery.js, jQuery.ui.js, ES5Shim.js (EcmaScript 5 shim), HTML5.js (HTML 5 shim), Modernizr.js, RequireJS.js, 960.css ….

Demo directory

This directory should indeed contain any demo files! This is an optional folder that will not be used by the rendering engine. It’s only there for curious people who want to see the possibilities of the ADX.

@ADX-Developers:

Please use that folder to demonstrate your expectations!
Be ingenious and used relative paths to the `Resources/` folders to also use your demos as a debugging system.

Examples directory

This directory is optional and will be ignored by the rendering engine. It contains survey file (QEX) as examples of ADX usage.

Tests directory

This directory is optional and will be ignored by the rendering engine.

It contains files necessary to test the ADX.

Units directory

This directory is use by the ADX unit test engine (ADXShell).

It should contains unit tests xml files.

The ADX unit test engine allows developers to fake a context (survey, properties, browser), run the rendering engine and assert against output.

It’s useful for developers to maintain the ADX, test non-regression but also to document the expected behaviour.
This unit-test tool implements the Test design pattern AAA

The unit tests could also be run in ADXStudio trough the menu Tools > Validation

Also see: Unit tests

Fixtures directory

Because sometimes tests use the same arrange, the fixture allows developers to partially arrange the test in a separate file and include that arrange in the unit-test files. In a test world this kind of share context is call a fixture. The fixtures directory contains .xml files which implement the UnitTests.xsd in order to create a share arrange across tests.

For examples:

• Create a fixture file SurveyA.xml which contains the XML definition of the survey that will be use by several unit tests
• Create a fixture file BrowserMobile.xml which fake a mobile browser
• Create a fixture file Firefox.xml which fake a Firefox browser
• …

Also see: Unit tests, Unit tests – Fixtures Section

Cases directory

Most of the time some tests are really equivalent, there are only few difference between them. Instead of copying tests over and over, which could be a pain to do and maintain, it is useful to loop through an enumeration of case and apply the tests inside the loop. To achieve this type of feature, we also implemented the cases .xml file in the /cases/ directory which hold all cases enumeration. These cases files also implement the UnitTests.xsd schema.

For example, let’s imagine an ADC with two outputs: fallback / withJavascript which could work with numeric and single questions, we can write all the following cases:

• “fallback output with numeric question”
• “fallback output with single question”
• “standard output with numeric question”
• “fallback output with single question”
• “fallback outputs with all questions”
• “standard outputs with all questions”
• “all outputs with single question”
• “all outputs with numeric question”
• “all outputs with all questions”

Also see: Unit tests, Unit tests – Cases Section

Preview.png

Screen-shot of the ADX output.

Readme.md and CHANGELOG.txt

Extra information of the ADX (description, installation, credits, …). The Readme file indicates the purpose of the ADX while the Changelog file indicates the differences with the previous versions.

Others files and directories

All others files and directories are ignored by the rendering engine. Developers are free to add additional items such as: Help, Tools, Specs, …

<< Definition | Config >>