Last updated October 29, 2012. Created by drozas on October 25, 2012.
Log in to edit this page.

In this section we will detail the execution flow using a basic pattern that can be found in the submodule patterns_examples: node.yaml. This file will be used as an example for the rest of the pages as well.

info:
  title: Example Article creation
  description: Creates an example article node
  author: QSCience
  version: 1.0
  category: Content
  core: 7.x
  author_website: http://qlectives.eu
actions:
  - create:
      tag: node
      type: article
      title: Test Article
      body: lorem ipsum ...
  • We can start taking a look at the hook_menu() in the file patterns.module, where we will find the association between the paths and the main functions: enable a pattern, remove a pattern, publish it, the main settings, etc.
  • The first function we will detail is patterns_list() (implemented also in patterns.module), since this is the first function to be called. This function returns the main form in
    which all the operations related to patterns are performed. In this function, the following operations are carried on:
    • Check if there is any parser to use.
    • Load JS and CSS libraries and prepare and render the form.
    • Load all the directories in which patterns files are stored.
    • Load all the patterns from the database: patterns_io_get_patterns() function in the file includes/io.inc. This function will also check if the version stored in the database is updated against the file system and update it if necessary.
  • Once we are in the menu we can enable, edit it or quick-run a pattern producing as a result a Pattern object. The next sections detail the steps carried out all these processes, that are described in the diagram below to have a general overview:

Enabling/Quick-running/Editing a pattern
The steps involved are described in the following subsections.

Enabling a pattern

When we click on “Run” or “Re-run” a pattern, the function patterns_enable_pattern() is called, using the PID as a parameter. This function will perform the following operations:

  • Check if there is any parser to use.
  • Check if the pattern identifier is valid (function patterns_utils_if_invalid_go_back() in includes/util.inc). It is checked if the identifier is numeric and exists in the DB, and in that case it will return the whole pattern object. Following our example, node.yaml's PID is 1, and after calling this function the value stored in the variable $pattern will be:

$pattern stdClass
CLASSNAME stdClass
pid 1
name node.yaml
format yaml
status 1
public 0
file sites/all/modules/custom/patterns/patterns_examples/patterns//node.yaml
updated 1348051211
enabled 1348575577
title Example Article creation
description Creates an example article node
pattern Array [2]
info Array [7]
title Example Article creation
description Creates an example article node
author QSCience
version 1.0
category Content
core 7.x
author_website http://qlectives.eu/
actions Array [1]
0 Array [1]
create Array [4]
tag node
type article
title Test Article
body lorem ipsum ...
  • Check if this is the latest version of the pattern.
  • Scan the pattern using the function patterns_scan_pattern() (includes/parser/scan.inc) to ensure the format is correct.
    • A pattern is correct if it satisfies the following conditions:
      • It has 1 and only 1 info section.
      • It has 0 or 1 module section.
      • It has at least one section different to the previous ones.
      • If an include section is found, the function is called recursively.
    • The scan function receives only the $pattern→pattern array, that in our example is:
      pattern Array [2]
      info Array [7]
      title Example Article creation
      description Creates an example article node
      author QSCience
      version 1.0
      category Content
      core 7.x
      author_website http://qlectives.eu/
      actions Array [1]
      0 Array [1]
      create Array [4]
      tag node
      type article
      title Test Article
      body lorem ipsum ...
    • The result of the scan will be an array with a summary of the process. As an example, this is the array returned by a successful scanning process applied to the node.yaml pattern:

      $scan Array [12]
      info 1
      modules 0
      empties Array [0]
      invalid_actions Array [0]
      extra_actions Array [0]
      missing_tag Array [0]
      other_sections Array [1]
      actions (create:1, modify:0, delete:0, include:0)
      contain_includes false
      include_scans Array [0]
      generic_errors Array [0]
      unknown_tag Array [0]
      tag_errors Array [0]
    • The results provided by the previous function are analyzed by the function _patterns_scan_validate_patternscan() (in includes/scan.inc). This function will loop through the array and generate a set of human-readable messages to provide more information in case there are some errors.
    • If the process was successful, we will return a confirmation form that also allows to choose the execution options (provided by the function patterns_forms_get_execution_options() in the file forms.inc).
    • The confirmation of that form produces the execution of the hook patterns_enable_pattern_submit(). In this function a pattern object will be retrieved using the PID (the formats are the same as in the previous step, since it is also performed using patterns_get_pattern() function), and sent to the function patterns_start_engine(). This is the function that begins the logic, due to its complexity it will be described in detail in a specific section called “Pattern Execution

    Quick-running a pattern

    When we quick-run a pattern, the behaviour will be similar to the one explained previously for enabling, but presenting an editor to allow users to write quickly a pattern. The following steps are taken:

    • The function patterns_editor() in the file includes/editor.inc is called, using 'patterns_quickrun' as a value for the parameter $form_id. This function constructs the quick-run form by calling the function patterns_quickrun() (in the file includes/forms/quickrun.inc) using drupal_get_form() and then try to load Codemirror libraries and returns the editor.
    • Once the form is submitted, the hook patterns_quickrun_submit() (includes/forms/quickrun.inc) is executed. The flow is similar to the one explained for patterns_enable():
      • First the function patterns_parse_parse() (includes/parser/parser.inc) is called, with the contents of the editor. This returns the pattern in an array format:
        $pattern Array [1]
        pattern Array [2]
        info Array [7]
        title Example Article creation
        description Creates an example article node
        author QSCience
        version 1.0
        category Content
        core 7.x
        author_website http://qlectives.eu/
        actions Array [1]
        0 Array [1]
        create Array [4]
      • The values returned are converted into a Pattern object, which is the format expected by the patterns_start_engine_function(). As an example, the same code that is executed in node.yaml launched with quickrun generates the following object:
      • pattern Array [2]
        info Array [7]
        title Example Article creation
        description Creates an example article node
        author QSCience
        version 1.0
        category Content
        core 7.x
        author_website http://qlectives.eu/
        actions Array [1]
        0 Array [1]
        create Array [4]
        tag node
        type article
        title Test Article
        body lorem ipsum ...
    • Finally some extra parameters (run-subpatterns, quickrun mode) are set, and the function patterns_start_engine() is called.

    Validating the patterns

    In case we decide to validate the pattern, the validation in this case is performed using AJAX.

    The ajax_validation.js file contains a function that will generate the url to ask for the service in the server. In this case the function will be pattern_validate_service() (in the file includes/parser/parser.inc):

    • It checks the $pattern and $format variables are sent by the client
    • It executes patterns_parser_parse(), _patterns_scan_validate_patternscan() and _patterns_scan_analyze_patternscan() in a similar way as it was previously explained in the previous parent subsection to display the errors or the successful message

    Editing a pattern

    • When an already stored pattern is edited, the function patterns_edit_page() (in the file includes/forms/editor.inc) will be called. This function will load the Pattern Object using the PID and call the common patterns_editor() function with 'patterns_edit' as a value for the $form_id argument.
    • The function patterns_editor() will create the form by calling the function patterns_edit() (includes/forms/editor.inc) using drupal_get_form(). The idea is the same as it was explained for the quick-run case (the equivalent function is patterns_quickrun()), but in this function we will also query the database to check the status of the pattern (patterns_db_analyze_patterns_status()) and then check if it should be loaded from the filesystem or from the database (in case it was removed from the filesystem).
    • When the form is submitted, the function patterns_edit_validate() is run, which checks if the directory in the filesystem is writable.
    • Finally, the hook patterns_edit_submit() is executed, and it will call the function patterns_io_save_pattern() with the content of the editor. This function is the responsible of storing the pattern in the database and the filesystem (in a similar way as it will be explained in the Import section).
AttachmentSize
enabling_qr_editing_pattern.png152.06 KB

Looking for support? Visit the Drupal.org forums, or join #drupal-support in IRC.