Home

= Repo Man for MODX Revolution =

This package has the following goals:

1. Allow developers of MODX packages to easily store all of a project's files in a single directory so it can be easily version controlled using Git.

2. Implement a logical and extendible folder structure and naming convention that will keep projects organized and thereby prepare local repositories so they may be synced with MODX without the need to install a package.

3. Offer a sync functionality inside a MODX custom manager page (CMP) that will create uncached static elements inside of MODX whose source is the files in your local repository(ies). This will allow developers to focus solely on the files in their repos while they develop. No more time wasted uploading changes into MODX.

4. Make the creation of transport packages as simple as possible via a single unchanging build.transport.php build script.

= Conventions =

The conventions expected by this package attempts to follow the conventions already in common usage amongst other MODX developers.

A repo should contain the following directories:

• _build -- contains the build script and any configuration details about the package, e.g. its name and version.
• assets -- contains any files/directories destined for the assets directory, accessible via http.
• core -- contains any files/directories destined for the MODX core directory.

core

The core directory follows this naming convention: core/components/{package_name}

The subdirectories here are commonly the following:

• controllers
• docs
• elements
• lexicon
• model
• processors

Of interest to the syncing functionality is the elements directory. This directory is scanned for chunks, snippets, plugins etc.

Any single file sitting on your computer acts much as a key/value pair: a file has a name and it has its contents; it does not inherently have any additional attributes. This works well enough for certain types of objects (such as Chunks), but not as well for others (such as TVs). In order to store more object attributes inside a single file, we rely on conventions in comment blocks. So the Repo Man package follows conventions similar to PHPDoc (http://en.wikipedia.org/wiki/PHPDoc).

1. The name of the object is by default the file name (stripped of any extension).
2. The content of the object is by default the contents of the file.
3. Any other attribute should be prepended with the @ symbol and exist within a comment block.

mychunk.chunk.html

Here is the content of my chunk.

The same style of comment block is used inside of Snippets and Plugins -- this should be a familiar syntax to anyone who has used JavaDoc or PHPDoc syntax:

mysnippet.snippet.php