New Front End Contributor Requirements for 2.3

MODX Revolution 2.3 introduces a grunt based workflow to building and preprocessing front end assets. This does not add any requirements to building MODX Revolution itself, just to contributing to CSS and JavaScript for the default manager theme.

Please see our overview of what you'll need to get started here:
https://github.com/modxcms/revolution/tree/develop/_build/templates/default

I've read that git page twice and understand none of it. Can you dumb it down for me?

No problem. To help me get an idea where to start, are you familiar using a command line interface such as Terminal on the Mac? Have you used Git or Github? [ed. note: dinocorn last edited this post 13 years, 1 month ago.]

In a nutshell:

1. Contributions have to be made via Github, so you need a Git clone of Revo on your development environment (presumably localhost) so your version can be kept in sync with theirs.

2. They're using node.js, which is server-side Javascript.

3. They're using a couple of ruby apps ("gems" - how cute), sass and compass, to work with css files.

4. Grunt and Bower are node.js apps, for working with Javascript.

All of this is supposed to make it easier to work with the Manager interface. I'm sure jpdevries will come back with a more detailed explanation.

Quote from: sottwell at Sep 05, 2013, 01:11 AM

In a nutshell:

1. Contributions have to be made via Github, so you need a Git clone of Revo on your development environment (presumably localhost) so your version can be kept in sync with theirs.

2. They're using node.js, which is server-side Javascript.

3. They're using a couple of ruby apps ("gems" - how cute), sass and compass, to work with css files.

4. Grunt and Bower are node.js apps, for working with Javascript.

All of this is supposed to make it easier to work with the Manager interface. I'm sure jpdevries will come back with a more detailed explanation.

That's a really good explanation. So to contribute to MODX in general you will need to be using Github. Once you've checked out the repository, if you want to make contributions to the Manager theme files you will need to get up and running with new tools. All the required tools are opensource, free, and run on Mac/PC/Linux.

Ruby
Odds are you already have the Ruby programming language on your computer but you can see how to Install Ruby and Sass here:
http://sass-lang.com/tutorial.html


Sass
Sass is a popular CSS preprocessor. We don't edit .css files, rather the files found in _build/templates/default/sass/. Sass syntax allows things like variables, reusable mixins, silent classes, but most importantly the ability to organize things in a more Object-Oriented way.


Grunt
Grunt is a task runner used for automation. It doesn't do one thing, it's more of an abstract tool comprised of many plugins that you can use to configure front end workflows. Once installed, you just need to run npm install from the default template. That will fetch any grunt plugins being used.

Now you can run any of the grunt tasks which are documented here:
https://github.com/modxcms/revolution/tree/develop/_build/templates/default#grunt-commands

Note: grunt prod task has been removed and replaced with grunt expand in this pull request
https://github.com/modxcms/revolution/pull/595

What is grunt?
http://gruntjs.com/

Grunt Plugins
http://gruntjs.com/plugins


Bower
Bower is a front end package manager by Twitter. Currently whenever the grunt build task is run the latest version of Bourbon is checked out from github, copied to the proper location of our project, and the full source code is stored bower_components, which is ignored by github.
http://bower.io/


Bourbon
Bourbon is a lightweight mixin library for Sass that is commonly thought of as alternative to Compass. Compass dependency has recently been removed in a pull request, and the README has been updated.
http://bourbon.io/

Going forward, this approach is going to be easier (by a long way) but I can see how this may be a learning curve too. With this process, we have a greater control of the styling of the MODX Manager. We're trying (and hopefully succeeding) to move away from the rigid styling that ExtJS has provided us so far.

The requirement to have access to Git and be able to push changes through GitHub is how we've been handling core code changes now for a long while. CSS updates are no different in this regard. Anyone who contributes must first ensure they have provided a CLA first, this is one of the biggest delays in getting your code contribution merged (and we love to merge code contributions so please complete those!)

The main change in workflow is the use of SASS and the need for grunt etc. - I totally understand the concerns people may have. As a a backend developer, I don't fully understand the in's and out's of SASS .... but I know the people that do will welcome this change. Let designers be designers

Installing the tools for local development such as node.js and the ruby gems is, unfortunately, one of the pre-requisites. Our ultimate goal is getting a streamlined, sweet-looking manager that can be tailored very quickly to a designer's needs.

Quote from: dinocorn at Sep 04, 2013, 06:45 PM

No problem. To help me get an idea where to start, are you familiar using a command line interface such as Terminal on the Mac? Have you used Git or Github?

Hi JP

I'm mainly a front end guy. Using a mac and have done some simple terminal commands.
Was mainly asking out of curiosity. I have a github acc for watching updates but don't know how to contribute.
Thanks for the explanation. Looking forward to learning more.

There is definitely a learn curve introduced and we are willing and able to work with anyone interested in contributing to get setup.

I hope the community understand aside from the immediate benefits, this is partly to recruit more front end contributors already familiar with these tools to the MODX ecosystem. Grunt workflows are becoming increasingly popular, and with good reason. Just look at what people are saying about them:
https://twitter.com/search?q=gruntjs&src=typd

If you are familiar with MODX, you probably cringe at the idea of creating an entire site using static HTML. To the same token, once familiar with Grunt and Sass, you will cringe at the concept of managing front end styles entirely in CSS. [ed. note: garryn last edited this post 13 years, 1 month ago.]

Quote from: eladnova at Sep 05, 2013, 03:01 AM

Quote from: dinocorn at Sep 04, 2013, 06:45 PM

No problem. To help me get an idea where to start, are you familiar using a command line interface such as Terminal on the Mac? Have you used Git or Github?

Hi JP

I'm mainly a front end guy. Using a mac and have done some simple terminal commands.
Was mainly asking out of curiosity. I have a github acc for watching updates but don't know how to contribute.
Thanks for the explanation. Looking forward to learning more.

Awesome. Since you are on a Mac, you'll want to install homebrew if you haven't already.
http://brew.sh/

You're Mac should already have Ruby but to find out:


If say it didn't have ruby, install it with:


Then install Sass:


Clone the modx/revolution repository:


Install grunt and bower globally (if you haven't already)


Set the current directory to the default manager theme and install node package dependencies:


Build the project


Lastly, if you would like growl notifications enabled install terminal notifier:

Just wondering what this means for making custom themes for the manager ? Will it still be as easy as editing html templates and readable css files?