How Marv works

Olibia Tsati edited this page Apr 5, 2015 · 26 revisions

Running marv create generates a skeleton project for developing your project. All of your development work takes place in the source directory of that project.

When you run marv watch, marv build, or marv package the underlying process is the same - Marv compiles the source directory into a working project. As we explain how Marv works, we’ll be referring to the final-project directory, which represents the "compiled" project.

The source directory is made up of 4 sections: Assets, Templates, Functions and Includes. You can choose which folders you need and remove the others. You can also create other directories in the source directory and they will be compiled in the final-project root directory.

Assets

Assets are your JavaScript, CSS, and image files. You may use CoffeeScript, Sass and LESS. If you want to stick with plain CSS and JavaScript, you can do that as well.

Assets fall into 3 categories: Stylesheets, JavaScript, and Images.

Stylesheets

Stylesheets in Marv use Sass or LESS, languages that make stylesheet development quicker and easier. When creating a theme, Marv generates source/assets/stylesheets/style.scss by default. If you want to compile extra stylesheets, see configuring Marv.

Marv supports both the Sass (.sass) and SCSS (.scss) syntax - just change the extension to style.sass if you prefer Sass syntax. Or, if you prefer LESS to Sass, just name your stylesheet file style.less, and the LESS processor will take over. Sass supports importing of partial stylesheets. Marv allows as many partials you want for breaking up your CSS into an organized structure.

For example, assume the following files exist:

source/assets/stylesheets/_pages.scss
source/assets/stylesheets/_reset.scss
source/assets/stylesheets/style.scss

Simply edit your source/assets/stylesheets/style.scss file to include these partials:

@import "reset";
@import "pages";

body { color: #333; }
…

style.scss will be processed and the result outputs to final-project/style.css.

JavaScript

JavaScript in Marv harnesses the power of CoffeeScript and Sprockets. When creating a theme, the master JavaScript file for your project is source/assets/javascripts/theme.js. If you want to compile extra javascript files, see configuring Marv.

In theme.js, you can include any other JavaScript or CoffeeScript files you'll need in your final project.

For example, with these files:

source/assets/javascripts/slider.js
source/assets/javascripts/tags.coffee
source/assets/javascripts/theme.js

Including other files is as easy as

(in source/assets/javascripts/theme.js)

//= require 'slider'
//= require 'tags'

$('#more .javascript .here').show();
...

theme.js will be processed and output to final-project/javascripts/theme.js

Marv also processes an admin JavaScript file, for scripts to be used only in the WordPress admin.

source/assets/javascripts/admin.js

This is processed the same way as theme.js, but outputs to

final-project/javascripts/admin.js

Read more about CoffeeScript and Sprockets.

Additional Assets

Additional assets in Marv are implemented very easily, just by editing the config.rb file in the source directory of your project folder.

Uncomment the following line to enable the compilation of additional assets.

# config[:additional_assets] = [['custom.js'], ['stylesheets', 'custom.css'], ['includes', 'javascripts', 'includes.js']]

Using the option above, you can compile for example custom.js in the root folder, custom.css in the stylesheets folder and includes.js in the includes/javascripts folder. You can add as many directories as you like.

Images

Images in Marv are kept in source/assets/images/

Everything in the images folder will be copied unchanged to final-project/images/

The only exception to this rule is your screenshot file - named screenshot.png, screenshot.jpg, screenshot.jpeg, or screenshot.gif. This file will be copied directly to the root of your project.

To clarify with an example - the following images folder setup:

source/assets/images/photo.jpg
source/assets/images/screenshot.png
source/assets/images/animals/wild/lion.jpg
source/assets/images/food/hamburger.png

would translate to the following:

final-project/images/photo.jpg
final-project/images/animals/wild/lion.jpg
final-project/images/food/hamburger.png
// screenshot goes in the root
final-project/screenshot.png

Templates

The templates directory is simply a way to organize your template files. For example when you are developing a theme, all templates would go in the root directory. With Marv, you can organize your templates however you prefer, and they’ll be moved to the root when the theme is built.

For example, the following set up:

source/templates/index.php
source/templates/pages/my-template.php
source/templates/this/is/getting/really-deep.php

will translate to this in your theme:

final-project/index.php
final-project/my-template.php
final-project/really-deep.php

Marv gives you some default folders that we think make sense, but there’s no specific structure required.

Functions

Marv copies source/functions/functions.php and source/functions/project-name.php as-is into final-project/functions.php and final-project/project-name.php. The other files from source/functions/ are copied into final-project/functions/.

To clarify with an example:

source/functions/functions.php
source/functions/project-name.php
source/functions/external-library.php

becomes

final-project/functions.php
final-project/project-name.php
final-project/functions/external-library.php

Includes

If you have any libraries you want to include with your project, you can put them into source/includes/ and they will be copied over directly into final-project/includes/.

To clarify with an example:

source/includes/options.php
source/includes/external-library.php
source/includes/javascripts/external.js

becomes

final-project/includes/options.php
final-project/includes/external-library.php
final-project/includes/javascripts/external.js

Extras

If you have extra folders you want to include with your project, you can put them into source folder and they will be copied over directly into final-project/.

To clarify with an example:

source/my-folder
source/my-other-folder

becomes

final-project/my-folder
final-project/my-other-folder

Server

Marv server creates a directory in your home folder under ~/.marv/servers. Inside that directory is stored every new server created with the command marv server create server-name, which carries a new Wordpress installation with the use of the built in PHP server and a MySQL database.

Global Projects

When you make a project global using marv link, it will be available on all servers created with Marv.

Plugins are linked in plugins folder

~/.marv/plugins

Themes are linked in themes folder

~/.marv/themes
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.