XML definition of polymod module rows

Each polymod module in Automne can use a <block> tag in the content rows, in order to use more or less complex dynamic content.

Here we deal with polymod modules, integrated into Automne’s core and thus perfectly compatible with these tags. Many parsing features are offered by using the <block> tag in a polymod module.

Module blocks

Dynamic help is available directly from the Automne administration interface.
You can access it while editing modules (pages and rows) by clicking on Help, under the “XML definition” tab.

All the polymod modules can natively use the <block> tag.

<block module="pnews" id="blockID" language="languageCode"> ... </block>

This tag displays data specific to the module. It must surround all the tags related to the treatment of module data.

  • blockID : Unique identifier of a block of content in the row. Two content blocks of the same row must not have identical identifiers,
  • languageCode : facultative) Language code related to this content block from among the codes available for your application (by default "fr" and "en").If not present the language of the page will be used.
  • If not present, the default language of Automne will be used.
  • lifetime (optional attribute) : This attribute lets you specify the duration of cache implemented on this block of data. It accepts the following values:
    • 0, false : Disable the client side cache for this block.
    • integer greater than 1 : Enables caching for the specified duration (in seconds).
    • 1, true, auto : Enables the cache automatically (default if the attribute does not exist).
      The automatic cache to a maximum of 24 hours. It will be activated only if the data block contains no PHP code. For more information see the operation of Polymod cache datas.

All the tags cited below must be situated in a block tag when the module is a “polymod.” If this is not the case the tags will not be correctly parsed and errors may occur. See the section regarding the block tag for PHP modules.

Searching module data 

Searches for a given object type :

<atm-search what="objet" name="searchName">...</atm-search>

  • object: Type of object to search for (in the form {object})
  • searchName: Name of the search: unique identifier for the search in the row.
  • A public attribute (facultative) may be added to specify a search in the public or edited area. It accepts true as a value for a public search (default) or false for a search in an edited area.

This tag can contain the following sub-tag :

Display results

<atm-result search="searchName"> ... </atm-result>

The content of this tag will be read for each result found for the search in progress.

  • searchName : Name of the search to which to apply the parameter.
  • A return attribute (facultative) can be added in order to specify the type of result returned. By default a search returns objects, but in the aim of improving results, it is possible to specify the two return values:
    • POLYMOD_SEARCH_RETURN_IDS will return only the identifier of the result. It can be recovered by {resultid}
    • POLYMOD_SEARCH_RETURN_OBJECTSLIGHT will return the result but without loading the sub-objects it can contain in its different fields. Attention, this parameter is not possible for a public search.

The following values will be replaced in the tag :

  • {firstresult} : True if the current result is the first of the current page.
  • {lastresult} : True if the current result is the last of the current page.
  • {resultcount} : Number of results in the page.
  • {maxresults} : Number of results for the search.
  • {maxpages} : Number of pages maximum for the current search.
  • {currentpage} : Number of the current page for the current search.
  • {resultid} : Identifier of the result. It is useful in the case of a search returning uniquely the identifiers of results (return parameter with the value POLYMOD_SEARCH_RETURN_IDS).

No result

<atm-noresult search="searchName"> ... </atm-noresult>

The content of the tag will be displayed if no result is found for the current search.

  • searchName : Name of the search to which to apply the parameter.

Search parameter

<atm-search-param search="searchName" type="paramType" value="paramValue" mandatory="mandatoryValue" />

Limits the results of the search to the given parameters.

  • searchName : Name of the search to which to apply the parameter.
  • paramType : Type of parameter, perhaps the form {objet:champ:fieldID} to filter the search for the value of a given field (see the dynamic help of the field).

Example, for a search "mySearch" in the "Recent Events" object, one wants a parameter for the "Category" field with the value {request:int:cat} :

<atm-search-param search="maRecherche" type="{Actualite:Categorie:fieldID}" value="{request:int:cat}" mandatory="true" />

Equally, it can be a fixed name, including :

  • object : The value is an object of the form {objet}, for example {News}
  • item : The value is an identifier of a polymod element. The value must be a positive integer. For example {var:int:newsid} can correspond to the '42' value
To display the identifier of a polymod element pass your mouse over the corresponding fields in the module management.
  • items : The value is a table of identifiers of polymod elements, in the array form (id1, id2, id3, ...). The search only uses these identifiers to return results. This is to say that the results of the search can only be from among the identifiers indicated in the table.

    For example a table PHP $items = array(1, 2, 3, 7); which is recovered with {var:array:items}

  • itemsOrdered : The value is a table of identifiers of polymod elements, identical to the items type, but here the results will be sorted as defined by the string value of the table. Any other sorting will be ignored.

    For example a PHP array $items = array(1, 7, 3, 2); which is recovered by {var:array:items}.

  • keywords : The value is a chain of characters.

    For example {var:string:keyword} which corresponds to the value "Search test"

One can distinguish 2 cases for the keyword type :

  1. The object for which a search is made is not indexed by the "Search engine" module:
In this case the polymod searches for the string value (words separated by spaces, commas and semicolons) in the indicated fields as “searchable.”
  2. The object for which a search is made is indexed by the « Search engine » module:
In this case the search engine ASE effectuates its own search and returns a table of polymod element identifiers to polymod. The search is thus based on the relevance of results from the search engine.

For your information, a search via the ASE search engine takes only the first 1000 results into account.

  • publication date after: The value is a date in the format of the current language. This parameter verifies that the object is a primary resource and has a publication start date greater than or equal to the indicated date.

    Example in French (language code = fr) : 15/03/2010.
Example in English (language code = en) : 03/15/2010.

    The Polymod module automatically converts the format of the entered date (for French this will be d/m/y, for English in SQL format: y-m-d.

The SQL request performed in the background verifies that :

    • the object is a primary resource,
    • the publication start date is different from "0000-00-00",
    • the publication start date is greater than or equal to the value indicated.

  • publication date before : The value is a date in the format of the current language. This parameter verifies that the object is a primary resource and has a publication start date lesser than or equal to the indicated date.

    Example in French (language code = fr): 15/03/2010.
Example in English (language code = en): 03/15/2010.

    The Polymod module automatically converts the format of the entered date (for French this will be d/m/y, for English in SQL format: y-m-d.

The SQL request made in the background verifies that:

    • the object is a "primary resource"

    • the publication start date is different from "0000-00-00"

    • the publication start date is greater than or equal to the value indicated.

paramValue :

Search parameter value. If the value is 'block' you can specify this value when creating a row in the page.

When the valued of a search parameter is "block", this allows an editor to select a predefined value while editing the page containing the polymod search. 

It is sometimes useful to recover the selected value to use it in PHP

If the value is defined, it is stored in a table in the following form: $blockAttributes['search']['mySearchName']['fieldID']

For example, for a search named "newsHomePage", if we establish a search parameter for the field that has 5 as an identifier and with a value defined as "block", the value selected by the editor can be recovered here: $blockAttributes['search']['newsHomePage'][5]

mandatoryValue :

Boolean (true or false), specifies whether this search parameter of optional or obligatory.

operator :

A supplementary operator parameter adds a specific behavior to the types of field in the filter. The value accepted by this parameter is explained in the field help, if it accepts this parameter.

Here are the operator attribute values according to the different existing fields:

  • Categories:
    • editableOnly: Only searches for objects associated with the editable category or categories supplies as a parameter.
    • strict: Only searches for objects associated with a category in parameter (the sub categories are not taken into account).
    • not in: Only searches for objects that are not associated with the category in parameter.
    • not in strict: Only searches for objects that are not associated with the category in parameter, in strict fashion (the sub-categories are not taken into account).
  • Character chains :
    • like: Allows making a search for an incomplete value. Use the % character to specify the unknown part. For example, "cha%" returns, "chariot", "champion", etc.
  • Date :
    • >= : Greater than or equal to
    • <= : Lesser than or equal to.
    • > : Greater than.
    • < : Lesser than
    • >= or null : Greater than or equal to or zero value.
    • <= or null : Lesser than or equal to or zero value.
    • > or null : Greater than or zero value.
    • < or null : Lesser than or zero value.
    • >= and not null : Greater than or equal to and non zero.
    • <= and not null : Lesser than or equal to and non zero.
    • > and not null : Greater than and non zero.
    • < and not null : Lesser than and non zero.
  • Integer :
    • < : Lesser than
    • <= : Lesser than or equal to
    • > : Greater than
    • >= : Greater than or equal to
  • Floating number (point)
    • < : Lesser than
    • <= : Lesser than or equal to
    • > : Greater than
    • >= : Greater than or equal to
    • like: Allows making a search for an incomplete value. Use the % character to specify the unknown part. For example, "cha%" returns, "chariot", "champion", etc.

Attention: If the operator attribute is not defined in the tag atm-search-param, the search is effected by default with the following parameter :

  • Basic field "text" : like '%value%'

  • Basic field "string" : like '%value%'

  • Basic field "date" : like 'value%'

  • Basic field "integer" (tableau) : in(value)

  • Basic field "integer" (entier) : = 'value'



Also see: Inheriting fields

Example of category field with a selectable value:

<atm-search-param search="homePageNews" type="{Actualite:Categorie:fieldID}" value="block" mandatory="true" />

Example of a "keyword" search parameter :

<atm-search-param search="homePageNews" type="keywords" value="{request:string:keywords}" mandatory="true" />

Displaying a given page of results (the number of results of a page is specified by the tag atm-search-limit):

<atm-search-page search="searchName" value="pageValue" />

  • searchName: Name of the search to which to apply the parameter.
  • pageValue: Numerical value of the page to display.

Limiting the number of results of a page:

<atm-search-limit search="searchName" value="limitValue" />

  • searchName : Name of the search to which to apply the limit..
  • limitValue: Numerical value of the limit to apply. If the value is 'block' you can specify this value when creating a row in the page.

Ordering the results:

<atm-search-order search="searchName" type="orderType" direction="directionValue" />

  • searchName : Name of the search to which to apply the limit..
  • orderType : Type of value to which to apply the order, which can be the form {objet:champ:fieldID} or a name of a fixed type such as: objectID, random, publication date after, publication date before.
  • directionValue: Direction to apply : asc for ascending, desc for descending.If the value is 'block' you can specify this value when creating a row in the page.

Functions

Displaying the list of pages for the search in progress:

<atm-function function="pages" maxpages="maxpagesValues" currentpage="currentpageValue" displayedpage="displayedpagesValue">
<pages> ... {n} ... </pages>
<currentpage> ... {n} ... </currentpage>
<start> ... {n} ... </start>
<previous> ... {n} ... </previous>
<next> ... {n} ... </next>
<end> ... {n} ... </end>
</atm-function>

This function displays the list of all the pages possible to search.

  • maxpagesValue: Maximum number of pages to loop (usually: {maxpages} ).
  • currentpageValue: Number of the current page from which you are searching (usually: {currentpage} ).
  • displayedpagesValue: Number of pages to display.
  • The <pages> tag will be read for each page to list except the current page and the value {n} will be replaced by the page number.
  • The optional tag <currentpage> will be read for the current page. If it does not exist, the <pages> will be used in its place.
  • The optional tag <start> will be read for the first page.
  • The optional tag <previous> will be read for the preceding page.
  • The optional tag <next> will be read for the following page.
  • The optional tag <end> will be read for the last page.

Works tags

Display the content of the tag if the condition is met:

<atm-if what="condition"> ... </atm-if>

  • condition : Condition to meet to display the content of the tag. Common use is to validate the presence of a non negative value. This condition may also take all the valid forms of a PHP condition (see: The structures of a PHP control). The condition will be met if the value exists or if it is not negative or if it is not equal to false.
  • An attribute name (optional) can be added if you want to run the opposite condition (else) using a tag atm-else (see below). This attribute can contain only alphanumeric characters (a-zA-Z0-9_. -).

<atm-else for="if-name"> ... </atm-else>

  • for: name of the atm-if tag of reference. The content of this tag will be displayed only if the condition of the tag atm-if of reference is not met.
  • An attribute what (optional) may be added if you want to add an additional condition to display the content of this tag. Common usage is to validate the presence of a nonzero value.  This condition may also take all the valid forms of a PHP condition (see: The structures of a PHP control). The condition will be met if the value exists or if it is not negative or if it is not equal to false.

Looping over a set of objects

<atm-loop on="objets"> ... </atm-loop>

  • objects : Collection of objects. Employed to deal with all the objects in a collection of multiple objects (called multi-object).
  • reverse (facultative) : attribute that can be added to inverse the order of results (value : Boolean true, false).

The following values will be replaced in the tag :

  • {firstloop} : True if the current object is first in the list of objects.
  • {lastloop} : True if the current object is last in the list of objects.
  • {loopcount} : Number of the current object in the list of objects.
  • {lastloop} : True if the current object is last in the list of objects.
  • {maxloops} : Number of objects to loop.

Adding an attribute to an XHTML parent tag (containing this tag)

<atm-parameter attribute="attributeName" value="attributeValue" />

  • attributeName : Name of the attribute to add.
  • attributeValue : Value of the attribute to add.

Assigning a value to a variable

<atm-setvar vartype="type" varname="name" value="varValue" />

  • type : Type of variable to assign : request, session or var.
  • name : Name of the variable to assign Attention, reassigning an existing variable deletes to old value.
  • varValue : value to assign to the variable.

Create an opening or a closing XHTML tag

In some cases, it may be interesting to create an opening or closing XHTML tag inside another tag (eg an atm-if tag). But this scenario breaks the XML syntax. In this case, you can use both tags:

<atm-start-tag tag="tagName" />

  • tag : Name of the opening tag to display.
  • You can then add as many attributes you want, they will all be added to the generated tag.

<atm-end-tag tag="tagName" />

  • tag : Name of the closing tag to display.

Example :

Your row contains the following code:

<atm-if what="condition1">
    <atm-start-tag tag="div" class="class1" />
</atm-if>
<atm-if what="condition2">
    <atm-start-tag tag="div" class="class2" />
</atm-if>
... some XHTML content ...
<atm-tag-end tag="div" />

If condition 1 is fulfilled, you will get the following code:

<div class="class1">
... some XHTML content ...
</div>

Reloading an area in AJAX

<atm-xml what="condition"> ... </atm-xml>

Reloads a specific area of the page via an AJAX request.

If the HTTP request calling the current page contains the parameter verifying the attribute condition, only the content of the atm-xml will be sent in response to the HTTP request. The rest of the page content will be ignored.

For more information, study the Polymod modules supplied with the Automne demo, they use this feature.

  • condition : Condition à remplir pour obtenir le contenu du tag atm-xml.

Example with JQuery

Your row contains the following code:

<atm-xml what="{request:string:out} == 'xml'">
    ... news search ...
</atm-xml>

If we make the following Ajax request to the page with the following row

$.ajax({
   type: "POST",
   url: pageURL,
   data: 'out=xml&cat=' + $('#cat').val(),
   success: displaySearch
});

The search for recent events will be re-launched with the parameter of the selected category and only the content of this area returned:

<?xml version="1.0" encoding="utf-8"?>
<response xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <error>0</error>
    <data><![CDATA[ ... the content of the atm-xml tag corresponds to the new recent events search ... ]]></data>
</response>

Referencing an element to the cache manager:

<atm-cache-reference element="element" />

  • element : Referencing a module using his codename: cms_aliases, cms_forms, cms_pdf, comments, pmedia, pnews, standard or an Automne user or group using the value: users.

This tag allows you to inform the cache manager that you use in a PHP code inserted into the block a given element (module or Automne users/groups). Thus, the cache manager can monitor the changes made on this element to refresh the cache if the referenced element is modified.

General variables

Variables related to pages

The variables related to pages haves the following form: {page:id:type}:

  • id : Identifier of the page to be referenced, perhaps a numerical identifier or even "self" to refer to a current page.
  • type : Type of data desired for the page from among the following: url (adress of the page), printurl (adress of the print page), id (identifier of the page), title (name of the page).

Attention, if you use this to generate the href of a link, this will always be displayed even if the user does not haverights to consult the page. Only atm-linx links verify rights before display.

Variables related to sent data (via an address or form)

The variable correspond to a variable coming from the submission of a form or even from a parameter of the link leading to the current page. They have the following form {request:type:name}:

  • type : Corresponds to the type of variable expected, from among the following:
    • int : integer,
    • string : character chain,
    • bool : Boolean,
    • array : Table of values,
    • email : valid email,
    • date : valid date without hour (returns a date in the MySQL format: YYYY-MM-DD),
    • datetime : valid date with hour (returns a date in the MySQL format: YYYY-MM-DD HH:MM:SS).
    • localisedDate : valid date without hour (returns a date in the format of your current language: jj/mm/aaaa).
    • name : Corresponds to the name of the desired variable (name of the parameter in the URL or name of the form field).

Session variables

These variables are available during navigation of the site by the visitor. They have the following form: {session:type:name}

  • type : Corresponds to the type of variable expected, from among the following:
    • int : integer,
    • string : character chain,
    • bool : Boolean,
    • array : Table of values,
    • email : valid email,
    • date : valid date without hour (returns a date in the MySQL format: YYYY-MM-DD),
    • datetime : valid date with hour (returns a date in the MySQL format: YYYY-MM-DD HH:MM:SS).
    • localisedDate : valid date without hour (returns a date in the format of your current language: jj/mm/aaaa).
    • name : Corresponds to the name of the desired variable (name of the parameter in the URL or name of the form field).

Variables

These variables correspond to the classic PHP variables. They have the following form: {var:type:name}:

  • type : Corresponds to the type of variable expected, from among the following:
    • int : integer,
    • string : character chain,
    • bool : Boolean,
    • array : Table of values,
    • email : valid email,
    • date : valid date without hour (returns a date in the MySQL format: YYYY-MM-DD),
    • datetime : valid date with hour (returns a date in the MySQL format: YYYY-MM-DD HH:MM:SS).
    • localisedDate : valid date without hour (returns a date in the format of your current language: jj/mm/aaaa).
    • name : Corresponds to the name of the desired variable (name of the parameter in the URL or name of the form field).

Variables related to users

Variables related to users have the following form: {user:id:type}.

  • id : User name of the user to be referenced, perhaps a numerical identifier or even "self" to refer to a current user (only if the client-side rights verification is activated in the Automne parameters).
  • type : Corresponds to the type of variable expected, from among the following :
    • login : username,
    • fistName : first name,
    • lastName : last name,
    • fullName : first and last name,
    • email : email,
    • language : returns a CMS_language object corresponding to the language of the user’s profile,
    • active : Boolean, true for active, false for inactive,
    • deleted : Boolean, true for deleted, false for existing

Form tags (création - modification).

Creating/modifying client-side objects

<atm-form what="objet" name="formName"> ... </atm-form>

This tag creates an input form for a new object (if this tag is not in a search result) or of the modification for an existing object (if this tag is found in a search result).

  • objet : Type of object to input (in the firm {object})
  • formName : Name of the form: unique identifier for the form in the row.

The following values will be replaced in the tag :

  • {filled} : True if the form is filled in correctly and its validation causes no errors
  • {required} : True if the form is filled in correctly and the required fields are left empty
  • {malformed} : True if the form is not correctly filled in and the values of certain fields are incorrect.

This tag can contain the following tags

Display of required fields

<atm-form-required form="formName">
... {requiredname} ...
</atm-form-required>

The content of the tag will be read for each field required while the form is being filled in

  • formName : Nom du formulaire sur lequel appliquer le tag.

Les valeurs suivantes seront remplacées dans le tag :

  • {firstrequired} : True if the current required field is the first of the current field.
  • {lastrequired} : True if the current required field is the last of the current field.
  • {requiredcount} : Number of the required field in the current form
  • {maxrequired} : Number of required fields in the current form
  • {requiredname} : Name of the required field in the current form
  • {requiredfield} : Required object field in the current form.

Displaying malformed fields:

<atm-form-malformed form="formName">
... {malformedname} ...
</atm-form-malformed>

The content of the tag will be read for each malformed field while the form is being filled in

  • formName : Name of the form to which to apply the tag.

The following values will be replaced in the tag:

  • {firstmalformed} : True if the current malformed field is the first of the current form
  • {lastmalformed} : True if the current malformed field is the last of the current form
  • {malformedcount} : Number of the malformed field in the current form.
  • {maxmalformed} : Number of malformed fields in the current form.
  • {malformedname} : Name of the malformed field in the current form.
  • {malformedfield} : Malformed object field in the current form.

Display of an input field

<atm-input field="{object:field}" form="formName" />

This tag will be replaced by the input area (form field) necessary for the correct input of information related to the type of field specified.

  • formName : Name of the form to which to apply the tag.
  • {object:field} : Object field managed by the form for which the input must be made

This tag can next immediately have the HTML attributes that will be reposted in the HTML of the generated field (width, height, id, class, etc.).

Display of a field with complex verification

<atm-input field="{object:field}" form="formName">
 ... <atm-input-callback return="returnValue" /> ...
</atm-input>

This tag validates the fields in an atm-form

  • returnValue : The presence of an atm-input-callback tag with the attribute return="valid" will validate the content of a field; in the absence of the tag or value other than "valid" the field will return a malformed error.

This example searches to sees if a user already exists for a given email, in which case blocking re-registration.

<atm-input id="participant-email" field="{Participant:Email}" form="quizInscription">
 <atm-search what="{Participant}" name="emailCheck">
 <atm-search-param search="emailCheck" type="{Participant:Email:fieldID}" value="{request:string:participantEmail}" mandatory="true" />
 <atm-result search="emailCheck">
 <atm-input-callback return="invalid" />
 </atm-result>
 <atm-noresult search="emailCheck">
 <atm-input-callback return="valid" />
 </atm-noresult>
 </atm-search>
</atm-input>



Bookmark and Share

Top