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:

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).