Tutorial Building a New Project

Perhaps the easiest way to learn Repoman is to use it to build a new MODX project.

Screencast: Creating a New MODX Package using Repoman

Grabbing a Starter Repo

First, create a directory inside of your web directory dedicated to the packages you are building. I like to name mine "repos/"

Next, you'll want to use composer to pull down a starter repo:

composer create-project craftsmancoding/repo-starter --prefer-dist

The "repo-starter" is a demo Repoman respository that you can use to kick the tires and get your project started.

Rename the "repo-starter/" directory to your package's name. Remember:

• The folder name should be lowercase only
• The folder name should not use hyphens (or dashes?) Sorry there's some confusion here with exactly how certain JS functions in the MODX manager handle these.
• This folder name will be your package namespace (a MODX namespace, not a PHP namespace).
• The folder name should match your package name inside of your composer.json file.

Edit your composer.json file. Update the various name and package descriptions to taste, just remember that JSON requires entries to be on one line, and it won't work if you break the syntax.

In your composer's "extra" attribute, pay close attention to the following:

• package_name : this should follow your namespace, but it can use capital letters. I avoid spaces here (again, sorry for confusion here: I don't know the exact requirements MODX puts on this)
• namespace : this is the MODX namespace. It should match your sub-folder name exactly
• category : This can be equal to the package_name, but spaces are ok -- this is the most human readable of all of these.

When syncing your project with Git, you must first create the repository (e.g. on Github). On the command line inside of your package root, run the following commands (substitute your repository URL):

git init
git remote add origin git@github.com:yourusername/yourpackage.git

This should connect your local directory with the remote repository hosted on Github. Your package is now under version control!

Editing Elements

Once you've got your version control ironed out, you'll want to have a look about the files in this sample repository. You could install it as-is into your site using Repoman, but it'd be nicer if you customized things first.

E.g. edit the Snippet name and edit the code and what it does! Edit the template, or remove it altogether! The starter project is meant to be tinkered with.

If you want to create your own Snippet, for example, you will want to follow Repoman's conventions.

• Save your Snippet file inside of elements/snippets/
• Save it using a PHP file extension.
• Add a DocBlock that includes the Snippet's name and description

Sample DocBlock inside of elements/snippets/Date.php

<?php
/**
 * @name Date
 * @description This Snippet prints the current date.
 *
 * SNIPPET PARAMETERS:
 *
 * &format (string) any viable formatting string to be passed to php's date function.
 *
 * USAGE:
 *
 * [[Date? &format=`Y-m-d H:i:s`]]
 *
 */

```