Repository for druidic animal forms for the 5th edition of dungeons and dragons.

• NodeJS v.8+
• Gulp CLI

It is recommended that you use a package manager like Homebrew or Chocolatey to install Node on your machine.

After you install Node, you will also need to install Gulp CLI. You can install it by running npm install -g gulp-cli from the terminal.

Once you have installed the above dependencies:

1. Clone this repository into your development folder
2. Navigate to the root of the project folder and run npm install from the command line to begin installing dependencies.

Once the project is installed, several commands can be issued from the root of the project folder:

gulp: Runs the default Gulp task. This builds the project with source maps from the app folder into the release folder, spawns a Node server, opens a new browser with the website at http://localhost:3000, and listens for subsequent changes. When you edit and save a new file, Gulp will recompile accordingly and refresh your browser window with the latest changes automatically.

The following optional commands are also available:

gulp build: Runs the above Gulp task without spawning a server.

gulp serve: Spawns a Node server and serves files from the release folder. This is useful if you want to proof the minified\production build before pushing it to a remote server.

When you are ready to move minified code to production, you can run the following command:

gulp build --minify: Runs the Gulp task without spawning a server and produces minified CSS and JS.

• app/ : ALL work should be done in the app folder. This is where your website's source code lives.
• release/ : When running Gulp, files from app are compiled into release. If you work out of the release folder, your work will be overwritten and you will be sad. Don't work out of the release folder.
• gulp/ : This contains all of the Gulp tasks that the project relies on. There is also a config.js file that most of the tasks reference to make file paths and preferences more manageable.
• node_modules/ : The folder where node modules are installed when you run npm install.
• .babelrc: The configuration file for ES6 presets.
• .csscomb.json: The configuration file that can be used with CSSComb or similar, editor specific plugins to automatically sort and format CSS declarations.
• .eslintrc : The configuration file to enforce syntactical rules for JS linting.
• .jsbeautifyrc : The configuration file that can be used with Sublime Text's HTML-CSS-JS Prettify and Atom's atom-beautify plugins. Allows you to format your HTML, CSS, JavaScript, and JSON code.
• .scss-lint.yml: The configuration file for "linting" Sass/SCSS files.
• gulpfile.js : This references all of the tasks in gulp/tasks/. Tasks are broken apart for organizational purposes and referenced when you run gulp.
• package.json : Contains the project's dependencies. Modules specified in this files are installed into node_modules when you run npm install.
• README.md : You're reading it.

Your HTML can be found in the app folder, and can contain references to reusable includes (which live in app/includes/). For example:

//= include includes/core/head.html

This allows you to write a piece of code once and reuse it in multiple places. When Gulp runs, it takes these includes and compiles the full HTML into the release folder.

Note: The paths in which these includes are referenced are relative to the HTML file you are authoring. If you include an include from another include, that path will need to be prefixed with "../" accordingly.

This project uses Autoprefixer to add vendor prefixes necessary for browser support to your styles automatically when processed. Because of this, you do not need to include vendor prefixes on a majority of declarations to support cross-browser styling. The current Autoprefixer settings include style property rules for the latest 4 versions of all major browsers, as well as any browser with a global market share greater than 1%.

Additionally, the project makes use of a custom sort order for css properties based on a box-model approach, aranged from the outside in. By using this standard, instead of a more common alphabetical system, the project allows related properties to be adjacent to each other in declarations while still maintaining some logic to the order. To help with this process, each project includes a .sass-lint.yml file to help enforce the order and code styling, as well as a .csscomb.json to help automatically sort properites while using your editor of choice.

Note: If you are using Node Version Manager (NVM) and wish to use a tool like CSSComb to manage your sort order automaticaly, you will have to configure your CSSComb plugin or installation to indicate where your current version of Node is installed. You can create a symlink between your Node installation and /user/local/bin.

Your styles live in the app/styles/sass folder, split amongst multiple *.scss partials. The Boilerplate comes with a number of partials pre-populated in this directory as examples, but they can be modified to meet the needs of the site.

All JS for the site is split into modules, found in the /scripts/modules directory. When the site JS is loaded, it checks the DOM for any element with a data-module attribute. If and element with that attribute exists, it loads the module with the name matching the value of that attribute.

When writing new modules, add them to the registry of imported modules listed in the app.js file and add data-module="[MODULE NAME]" to the element that requires the script.

This project makes use of Babel, a compiler that allows you to write ES6 style JS in the project and still maintain browser-compatible JS for production.

• app/scripts/app.js : This is your application bootstrap. All JS kicks off from here. This file is where the registry of imorted modules is created.
• app/scripts/modules/ : This is where your site/feature scripts are located. Each module should be related to only one feature. The Common.js file in this folder is the only module that fires on every page, regardless of data-module attribute in the DOM. Place site-wide scripts here.
• app/scripts/libs/ : This is where your vendor libraries and plugins live if a NPM package has not been made for the required vendor code. Use this directory as a last resort. Otherwise, libraries and plugins are found in the node_modules directory.

Make sure you've installed ALL dependencies specified above. Also, make sure you have the most up up-to-date version of Node.

If you continue to have issues, especially after updating to a newer version of Node, delete the node_modules directory and package-lock.json file and re-run npm install.

The watch task only picks up on changes made to files that existed when the task was started. When you add any new file to the app folder, you must stop and restart Gulp.

The project uses linting rules which enforce specific CSS formatting standards, including a custom sort order (See "Writing SASS"). Make sure to follow those guidelines before committing finalized code to the repository. You can use tools like CSSComb to automatically match these standards in the editor of your choice.

The watch task only picks up on changes made to files that existed when the task was started. When you edit a Gulp task, a config file, or add any new file to the app folder, you must stop and restart Gulp.