Fields Creation and modification

Definition

Object fields structure and define the information of the elements which will be created from these objects.

An object is thus constituted of one or more fields. The number of fields per object is not limited but it is better not to overload an object with too many fields, especially complex fields (for example, “multi-object” fields).

Example : For the “Recent Events” module there will be “News” objects that have several fields:

  • Title (string field),
  • Category (categories field)
  • Description (text field with WYSIWYG editor).

Properties

Field editing form

The form for creating and modifying a field is composed of the following fields:

  • Datatype: Defines the type of data in the field.
  • Title: Specifies the title of the field. This label will be visible while editing an element.
  • Description: Describes a field. The description generally complements the title of a field. The description is visible while editing an element; it can be found next to the title of the field.
  • Parameters: Specifies the parameters for the field. Certain parameters are common to all fields, other are specific according to the type of field.

Groups of fields

We can organize the fields into 3 types:

  • Simple objects: Fields which do not involve the use of other objects,
  • Compound objects: Fields that use other objects. The value will be a unique element of these objects. The objects designated by a “Compound objects” field are usually called “sub-objects”,
  • Multiple compound objects: Fields that use other objects. The value can be an element or several elements of these objects. Objects designated “multiple compound objects” are usually called “sub-objects”.

Parameters of fields

Common parameters:

Each type of field has parameters. Some are common to all fields:

  • Required field: Defines whether or not the value of the field is necessary in order to validate the saving of an object,
  • Add a new search from (or search by key-word in this field): Note that this field has 2 effects:
    • Searches a field in the admin interface of the elements,
    • If the object is defined so as not to be indexed by the “Search Engine” module (ASE, Automne Search Engine): during a client-side search for a search parameter of “keywords” the field will be searched (with the help of a “like %value%”).
  • Indexed in the search engine: this field is only available if the object is defined as indexed by the “Search Engine” module (ASE, Automne Search Engine): If this is the case, the Search Engine will index the value of the field when it indexes objects,
  • Visible in the results of a search: Displays the field and its value in the list of results of the elements admin interface.

Other parameters are specific to certain types of fields. We will detail these parameters by detailing the types of fields.

Parameters of “compound object” fields

All multiple compound object fields have the same parameters because it is a particular type of field.

Forcing sub-objects to load: This parameter forces the loading of sub-objects situated above the second level of the object tree.

Attention! For performance reasons this parameter is generally deactivated. Do not activate in unless data is missing during certain page loads and if the cause is known. Activating this parameter can lead to a significant loss of performance.

Parameters of multiple compound objects fields

All multiple compound object fields have the same parameters because it is a particular type of field.

  • These objects can be edited: Specifies if the element can be edited directly on the form of their parent element.
    • No: The value will be selected from among a list of available elements, in the form of options in a selection box.
    • Yes: The value can be selected from among a list of available elements, in the form of options in a selection box. It will also be possible to modify a selected element or to create a new one. The forms will thus overlap.
  • Force sub-objects to load: This parameter forces the loading of sub-objects situated above the second level of the object tree.

    Attention! For performance reasons this parameter is generally deactivated. Do not activate in unless data is missing during certain page loads and if the cause is known. Activating this parameter can lead to a significant loss of performance.

  • Deactivate the association of sub-objects: This option will prevent the use of sub-elements created outside of the main objects. It is only useful if "these objects can be edited" is active. If this parameter is active it will only be possible to add a new element or to modify one already associated.

The different types of types of fields

Details of types of “simple object” fields

  • Boolean : Specifies a state. (Yes – no).
    This type of data is usually used for every field where the value must be either 0 or 1. For example a “Visible public side” field defines if an element should be displayed or not. The value will be verified when searching for elements on the public side,
  • Categories: Categorizes objects and manages their access rights. Specific parameters:
    • Multiple categories: Specifies if the field accepts a unique value (identifier of a category) or a multiple value (several identifiers or categories),
    • Highest level category: Specifies the highest-level category in order to display only its sub-categories in the selection menu,
    • Default category: Indicates which category will be selected by default if no category is chosen,
    • Authorize the association of unused categories: In the case of a row in which a search parameter has a “block” value, this indicates if the unused categories (those not associated with an element) must be displayed or not in the field value selection interface on the admin side,
    • Width of selection box (pixels): Indicates the width of the field selection menu in a form. This parameter is only used in the case of a “multiple categories” field,
    • Height of selection boxes (pixels): Indicates the height of the filed selection menu in a form. This parameter is only used in the case of a “multiple categories” field.
  • String: String containing 225 characters maximum, without HTML. Specific parameters:
    • Maximum number of characters: Indicates the maximum number of characters for the field value. This number must be below 256 characters. Note that the number of characters is not limited by the SQL structure but controlled only in PHP,
    • The value of the field must be a valid email address: Indicates if the string indicated in the value must be a valid email address. If this is the case, a verification is performed when the value is saved,
    • Format to respect: Specifies a format to respect using a PERL regular expression. See format help.
  • Text field: Long text field, with or without HTML. Specific parameters:
    • HTML authorized: Specifies if the field authorizes HTML or not. If yes, the WYSIWYG editor will be integrated into the input field,
    • Type of text editor toolbar (WYSIWYG): If the file authorizes HTML, this defines which WYSIWYG toolbar to use in the input field. See the WYSIWYG toolbar section.

      A noter que ce paramètre permet l'utilisation de certains plugins spécifiques à Automne et intégré via la barre d'outils du WYSIWYG. Par exemple l'utilisation du plugin lié à la docuthèque qui permet d'intégrer des éléments « Documents » dans le champ de type texte,

    • Width of the editor: Specifies the width of the input field. Value indicated in pixels,
    • Height of the editor: Specifies the height of the input field. Value indicated in pixels.
  • Date: Field containing the date in the format of the current language. Specific parameters:
    • Save the current date: If no value is indicated during input, the current date will be saved automatically,
    • With hours-minutes-seconds management: Defines if the format of the date will indicate hours, minutes and seconds,
    • Date of object creation: If activated, this parameter automatically saves the object creation date.

      Note that by “object creation date” we mean the first time the element input form is validated, when the date field is present in the form. In effect, if the date field is added to objects after the element is created, the date saved will be the date when the form is again validated for this element and not the real object creation date.

    • Date of object update: If activated, this parameter automatically saves the object modification date. That is to say the date which the data input form is validated,
    • Time Shift: If “today’s date”, “creation date” or “update date” is selected, this parameter shifts the value by the indicated duration (See the format of the strtotime feature).
  • File: Field containing a file. Specific parameters:
    • Use a thumbnail for the file: Saves a thumbnail which will be associated with the file. Authorized extensions: gif, jpg, png (this list of extensions is integrated into the core of the Polymod module and cannot currently be modified in administration),
    • Maximum width of the thumbnail in pixels: Used only if a thumbnail is specified. If the thumbnail exceeds this width it will be resized,
    • Maximum height of the thumbnail in pixels: Used only if a thumbnail is specified. If the thumbnail exceeds this height it will be resized,
    • Authorize using files from FTP directory: Uses an Automne directory in order to transfer large files via FTP),
    • FTP directory path to use: Specifies the path from which the files will be recovered. Used only if the use of an FTP directory is specified. You must indicate an empty path to prevent using an FTP directory as a source for documents,
    • Authorized extensions: Indicates the extensions that are authorized to load on the server: these extensions, separated by a comma, are considered as a whitelist. Note that if the “Prohibited extensions” parameter is defined, the corresponding extensions will be verified as well as these,
    • Prohibited extensions: Indicates the extensions which are not authorized to load on the server: these extensions, separated by a comma, are considered as a blacklist. Note that if the “Authorized extensions” parameter is defined, the corresponding extensions will be verified as well as these, 

      By default the following extensions are prohibited: exe, php, pif, vbs, bat, com, scr, reg

      Attention: do not modify this list unless really necessary; there can be serious consequences for site and server security.

  • Image: Field containing an image. Specific parameters:
    • Maximum width of the thumbnail in pixels: Used only if a thumbnail is specified. If the thumbnail exceeds this width it will be resized,
    • Maximum height of the thumbnail in pixels: Used only if a thumbnail is specified. If the thumbnail exceeds this height it will be resized,
    • Use a separate zoom image: Loads a zoom image in addition to the original,
    • Use the original thumbnail for the zoom image: Used only if the “Use a separate zoom image” is not activated. When this parameter is activated the original image loaded on the server is conserved as the zoom image,
    • Length of the thumbnail in search results: Used only if the field is visible in the results of an admin side search. This parameter defines the length of the image in the list of results. The length must be indicated in pixels. By default the length is 16px.
  • Language: Language of the object: Establishes a relationship with the languages available in the application. If the object is referenced for the “Search Engine” module (ASE or Automne Search Engine), this field is needed for correct indexing. For each element with a “Language” field, the Search Engine verifies the defined language and adapts to the words stemming from this language, if it is supported,
  • Link: Field containing a link. This field accepts different kinds of links:
    • Internal (towards an Automne page of the current site),
    • External (to another site),
    • To a file (loads a file on the server). Note that this type of field blocks by default the following extensions: exe, php, pif, vbs, bat, com, scr, reg.

      This list is defined by the PHP constant: php FILE_UPLOAD_EXTENSIONS_DENIED (defined in /cms_rc.php)

      Each link can be sent to different destination:

      • Current window,
      • New window,
      • Pop-up window.
  • Integer: Integer of 11 figures maximum.

    Specific parameters:

    • Can be zero: Specifies if the value can be zero, or not.
    • Can be negative: Specifies if the value can be negative, or not.
    • Unit: Specifies the value unit. The indicated unit will be displayed next to the value when the field is displayed. This parameter can also be recovered by a personalized display. For example: euros, meters, m², minutes, etc.
  • Floating number: String containing a floating point number with 255 characters maximum. Specific parameters:
    • Maximum number of characters: Specifies the maximum number of characters authorized for the field value. This number cannot exceed 255 characters.
    • The field value can be a negative number: Specifies if the value can be zero, or not.
    • Format to respect: Specifies a format to respect using a PERL regular expression. See format help.
    • Unit: Specifies the value unit. The indicated unit will be displayed next to the value when the field is displayed. This parameter can also be recovered by a personalized display. For example: euros, meters, m², minutes, etc.
  • Notification by email: This field sends an email notification when validating an element. If this field is part of an object, the validation of each element of the object sends one or more emails according to the field parameters. Specific parameters:
    • Email subject: Defines the subject of the email sent. The value must be a string of characters.
    • Email body: Defines the body of the email sent. The value can either be an HTML text (where it is possible to use tags specific to the module: see help available for the field), or an Automne page.
    • Send choice: When editing objects, chooses if the email is sent, or not.
    • Send: Indicates when emails are sent.
      • At validation: The email will be sent automatically at object validation
      • System event: The email will be sent by a specified system event. In this case the developer must put in place a PHP code specifically to send mails.
    • Include files: Includes the files of objects as an email attachment.
    • Email sender: Specifies an address for the email sender. If no value is indicated, the “postmaster” address will be used.
    • Inclusion: Defines the users or groups who will be included or excluded from the email notification.
      • yes: the selected users/groups will receive notifications
      • no: the selected users/groups will not receive notifications.
  • Page: Chooses an Automne page. The value corresponds to the identifier of an Automne page. A link to the site map is proposed to the user allowing him/her to select the desired page.
  • User/Group: Associates one or more users or groups with the element. Specific parameters:

    Note that if this parameter is used it excludes the others.

    • The value is the current user: Specifies a format to respect using a PERL regular expression. See format help.
    • User groups: If this parameter is selected the value will correspond to user groups. If not, it will be users.
    • Multiple users or groups: If this parameter is activated, the choice can be multiple. The value will be a table of identifiers (users, or user groups).
    • Inclusion: Defines the users or groups who will be included or excluded from the email notification.
      • yes: the selected users/groups will receive notifications
      • no: the selected users/groups will not receive notifications.
    • User creating the object: Specifies a format to respect using a PERL regular expression. See format help.

Inheriting fields

Technically, each field is inherited from a common base, thereby extending its properties. All fields inherit the common field but are sometimes made up of multiple types.  For example an email field is made up of three sub-fields: integer, date and integer.

Boolean:

  • Integer (int)

Category :

  • Integer (int)

Date :

  • Date (date)

Email :

  • Integer (int)
  • Date (date)
  • Integer (int)

File :

  • String (string)
  • String (string)
  • String (string)
  • Entier (int)
  • String (string)

Flottant :

  • Integer (int)
  • Booléen
  • String (string)
  • String (string)

Link :

  • String (string)

Image :

  • String (string)
  • String (string)
  • String (string)

Integer :

  • Integer (int)

Language :

  • String (string)

Page :

  • Integer (int)

String :

  • String (string)

Text :

  • Text (text)

User / group :

  • Integer (int)
Knowing the sub-fields can be useful in order to know how searches are done in these fields: By default a tag will search according to the value of each sub-field. See XML definition of polymod rows.

Actions

  • To add a field, click on the “New” button,
  • Can also modify each field with the “Modify” button,
  • To delete a field use the “Delete” button.

  • Attention: this action deletes a field and should be done with caution; some rows may use this field and will not work if the field is deleted. Delete a field only if you are certain that the action will not have undesired consequences.
  • The order of fields can be modified. One can simply drag and drop a file to the desired location. The order of fields is generally used for the editing form of an element; the fields are thus displayed according to the order defined therein.


Bookmark and Share

Top