-
Notifications
You must be signed in to change notification settings - Fork 7
DocBlocks
Inside Repoman, "DocBlocks" refer to blocks of documentation, the syntax loosely following those used in PHPDoc. These blocks are comments in your PHP code (or in your HTML) that use "@" to denote object properties, for example:
<?php
/**
* @name MySnippet
* @description This is my snippet
* @static true
*/
Although thorough documentation of your code is encouraged, these DocBlocks comments serve an important function when they are parsed by Repoman: they define object attributes. This saves time and it ensures that your Elements have better documentation (win-win!). This only applies to MODX Elements: Snippets, Chunks, Plugins, Templates (TVs are handled more elegantly as https://github.com/craftsmancoding/repoman/wiki/Seed-Data[Seed Data]).
Only the first comment block is considered when DocBlocks are parsed by Repoman, and certain standard DocBlock attributes are ignored (e.g. @param, @return, @author, etc.). Some special attributes (e.g. @PluginEvents inside a plugin) refer to related objects, but mostly the attributes correspond 1 to 1 to the object properties so that any valid object attribute may be specified as a DocBlock attribute, e.g. @property_preprocess for a Snippet or @templatename for a Template. The most common attributes are shown below.
-
Default Directory :
elements/chunks/ - Filename : no restrictions, e.g. x.tpl, mychunk.chunk.html, zzz.php
Example
<!--
@name MyChunk
@description This is my chunk
@static true
-->
This is my chunk...
-
Default Directory :
elements/snippets/ - Filename : .php files
Example
<?php
/**
* @name MySnippet
* @description This is my snippet
* @static true
*/
return 'Hello world...';
-
Default Directory :
elements/plugins/ - Filename : any PHP file
Example
/**
* @name Bloodline
* @description Add ?BLOODLINE=1 to your URLs to trigger verbose info to help debug problems, profile speed issues, and quickly find page components.
* @PluginEvents OnLoadWebDocument
*/
The @PluginEvents attribute is special: you can include a comma-separated list of events that the Plugin should be attached to.
-
Default Directory :
elements/templates/ - Filename : no restrictions, e.g. x.tpl, mychunk.template.html, zzz.php
Example
<!--
@templatename One-Column
@description My sample template using Bootstrap
@TVs CustomFooter
-->
<html>
<head>
<title>[[*pagetitle]]</title>
...etc...
Remember that templates use the "templatename" attribute, not the "name" attribute!
When Referencing TVs, you can use the @TVs attribute and comma-separate the names of the TVs. The name must match the filename exactly (minus the ".php" extension). For example, if you want to associate your template with a TV named "youTube", Repoman will look for a file named "youTube.php" in your repo's elements/tvs/ directory. See below for the TV syntax.
-
Default Directory :
elements/tvs/ -
Filename :
{tvname}.php
Template Variables do not use the DocBlock syntax because it simply is not a good fit for the complex data that a TV definition represents. In Repoman, a TV is defined as https://github.com/craftsmancoding/repoman/wiki/Seed-Data[Seed Data]: this is more appropriate as its data is a complex array. The only difference is that TVs are defined in the elements/tvs/ directory and not in the regular seed data directory.
WARNING: The file name is important! It must match the TV "name" attribute exactly (it is case sensitive). E.g. if the "name" attribute is "foo", then the file must be named elements/tvs/foo.php.
<?php
return array(
'type' => 'text', // hidden|text|file|etc...
'name' => 'Test', // <-- this must match the file name exactly (minus .php)
'caption' => 'This is my caption',
'description' => 'My description',
'editor_type' => 0,
'display' => '', // default
'default_text' => '',
'properties' => '',
'input_properties' => '', // serialized
'output_properties' => '', // serialized
);
?>
MODX allows you to define properties on any Element (and optionally to use property sets to group them together). You can define properties on your Elements by defining @param attributes in your DocBlock. The syntax must be:
@param type $paramName description [default="Default Value"] [options=mixed]
- string (also textfield)
- boolean (also bool, combo-boolean)
- integer (also numberfield)
- list (relies on the "options" argument).
The options argument is usually used to provide an array of values (for a list option). This should be a JSON array or hash.
Simple array:
[options=["asc","desc"]]
Hash (key/value pairs where key is stored in the database, value is displayed to the user):
[options={"asc":"Ascending","desc":"Descending"}]
Sometimes you don't want an element to be imported as a MODX object, for example if you are using MODX Chunks to format output of a Custom Manager Page (i.e. it should not be made available to other Snippets). Maybe saving the Chunk inside of elements/chunks/ might be the most logical location, but you don't want to clutter the MODX manager with Chunks that should not be editable by the user.
- @no_import - if set, the element will not be imported.
Also, you can set the require_docblocks config setting to true: if true, only elements containing a valid DocBlock will be parsed and imported.
© 2014 and beyond by Craftsman Coding