A34File

The a34 file is the heart of the generator. It's a DSL that allows you to define the elements composing the pages of your site. The Eclipse plugin gives you an editor for this type of file, with syntax coloring, auto-completion and some validation checking.

The first line of the file is the site name and package,
Site Google package net.sf.atomic34.example.google
The package is used to as a java package for the generated code.

Next comes the pages and component. A page represent a page on your site and a component is a part of a page that is usually reused in more than one page, for example, a site header or navigation menu. Components can be global (usable in every pages) or local to a page. You create local compoment for the safe of readability or as we will see later, to create a component list.

Pages use that following syntax:

page <Name> {
    path "relative or absolute path here" {
        <parameters here>
    }
    <elements here>
}

• The path of a page can either be relative or absolute. The base path of relative urls can be specified in your unit test, in case you have multiple site with the same elements to tests.
• Parameters can either be pathparameter or querystringparameter. pathparameter are mandatory and querystringparameter can either be optional or mandatory.
  • To define a pathparameter the syntax to use is pathparameter <name>. pathparameters should also be present in the actual url in the form of {name}. For example to define the pathparameter language the url could be /mysite/{language}/index.html. If the parameter is missing from the url it will have no effect.
  • To define a querystringparameter, the syntax is querystringparameter <name in code> named <name on the url> {optional}. querystringparameter don't have to be present in the url since that will be added at runtime (order of parameters in a query string should not matter)
• elements are defined using the syntax element <name> <type> <selector>
  • basic element types are field, image and text. They all use the same syntax, for example element nameField field selected by css "input#name". The selector syntax will be explained later.
  • links elements are similar to the basic types but that use an additional element at the end, the transitions keyword. In Atomic34, a link is an abstraction. A button can be a link. The point of links is that they allow a transition to another page, what ever the underlaying html element is. element searchButton link selected by css "button#search" transitions { Search } define a searchButton element that lead to the Search page. The Search page must be defined somewhere in the a34 file as the editor enforce it.
  • another type of element is the components. elements of type component refer to a component that has been defined in the file. For example, element toolbar component Toolbar would refer to a Toolbar component meaning that the page contains that component.
  • finally, the last element type is list of components. This type is used for a component that repeat itself many time. This is useful for anything that use repetitions like table rows, html list, ... For example, if we have a search result where each result is a LI tag containing an image, a text and a link, we could define a component SearchResultElement containing a image, a text and a link, and then use this syntax to define a list of SearchResultElement, element searchResults list of components SearchResultElement selected by ul#results li . Since the SearchResultElement component is only used inside this page, we don't have to define it globally in the a34 file. We can define it inside the Search page inside the scope of { ... }

Here is a complete example defining elements of the google homepage.

Site Google package net.sf.atomic34.example.google {
    page WebSearch {
        path "/webhp?hl=en&tab=iw" {
            querystringparameter SearchQuery named q optional
        }
        element toolbar component Toolbar
        element queryInputField field selected by css "input#lst-ib"
        element searchButton link selected by css "input[name='btnG']"
            transitions { WebSearchResults }
        element searchButtonLucky link selected by css "input[name='btnI']"
    }

    page WebSearchResults {
        element toolbar component Toolbar
        element results list of components SearchResultElement 
            selected by css "ol.rso li"
        component SearchResultElement {
            element title link selected by css "h3.r"
            element url text selected by css "cite"
            element shortDescription text selected by css "span.st"
        }
    }

    page ImageSearch {
        path "/imghp?hl=en&tab=wi" {
            querystringparameter SearchQuery named q
        }
        element toolbar component Toolbar
        element queryInputField field selected by css "div#qbc input[name='q']"
        element searchImagesButton link selected by css "input[name='btnG']"
    }

    component Toolbar {
        element webLink link selected by css "div#gbz ol li:nth-child(1)" 
            transitions {
                WebSearch
            }
        element imagesLink link selected by css "div#gbz ol li:nth-child(2)" 
            transitions {
                ImageSearch
            }
    }
}

Continue at [Writing jUnit tests]