ucf-athena-framework

A front-end web framework for UCF websites and applications


Keywords
athena-project
License
MIT
Install
bower install ucf-athena-framework

Documentation

Athena Framework

A front-end web framework for UCF websites and applications. Developed and maintained by UCF Web Communications.

Quick Links


Development

These instructions are for installation and development of the project for core development of the Athena Framework. If you're looking for instructions for installing and using the framework in your project, see our documentation.

Installation requirements

Installation instructions

  1. Clone the framework repository onto your machine:

    git clone git@github.com:UCF/Athena-Framework.git

  2. Navigate to the root Athena-Framework/ directory and install dependencies:

    cd Athena-Framework/

    npm install

  3. Create a copy of gulp-config.template.json, modify settings as needed for your local development environment (available options are listed below), and save as gulp-config.json.

  4. Navigate to the _docs/ directory and install dependencies for the framework docs:

    cd _docs/

    bundle install

  5. Navigate to the _examples/ directory and install dependencies for the examples site:

    cd _examples/

    bundle install

  6. Navigate back to the root directory of the project, and run an initial full build of the framework, documentation, and examples:

    gulp setup

That's it! Once you've finished all those steps, the root directory of the repo should look like this:

 ├── _docs/
 ├── _examples/
 ├── dist/
 ├── docs/
 ├── docs-local/
 ├── examples/
 ├── node_modules/
 ├── src/
 └── ...

(We're excluding git-related files in this example, as well as your gulp-config.json and the top-level config files that should have been cloned down from the project on Github, such as gulpfile.js and package.json).

Here's a rundown of what's in each of these directories:

_docs/

Contains source files for the framework's documentation. Athena's docs are built on Jekyll, meaning that they consist primarily of Markdown files.

Documentation files get built to one of two locations: docs-local/ or docs/. docs/ contains production-ready files intended to be served via Github Pages, and requires some unique options that we can't use for local testing. Because of this, the documentation site will only get built to docs/ when Athena's maintainers publish a new tag. If you're working on updates to Athena's documentation, you'll always build changes to docs-local/.

_examples/

Contains source files for local example pages that you can use to test changes to the framework against. Like the framework docs, these framework pages are built on Jekyll (but they are totally separate Jekyll instances.)

The examples site will get built to examples/.

dist/

Contains distributable framework files, including fallback fonts, minified CSS, and minified JS.

docs/

Contains production-ready documentation files to be served on Github Pages. These files should never be edited directly or be included in commits to the repo--they'll only ever get changed by Athena's maintainers when a new release of the framework is published.

docs-local/

Contains your local copy of the built-out documentation site.

This directory is included in our .gitignore, so only changes to the source files (in _docs/) are tracked via git.

examples/

Contains built-out static site files for Athena's example pages, which are intended to be used for testing changes to the framework's core CSS and JS.

The examples/ directory is included in our .gitignore, so the examples site will never be committed to the main repo--the site exists strictly for local testing.

node_modules/

Contains project dependencies installed via npm.

src/

Contains the primary source files for the framework, including font files, Sass, and JavaScript.

Framework development workflow

The Athena Framework comes with an extensive set of gulp tasks, which we use as the primary means of automating repetitive tasks, such as minification, concatenation, and moving of files.

Your general workflow when working on the Athena Framework will look something like this:

  1. Download + install the framework. Run gulp setup once before running watch tasks for the first time.
  2. Run gulp watch to watch changes to Sass and JS files in src/, and automatically perform CSS and JS build steps whenever changes are made. Changes to example pages are also watched with this task.
  3. When making changes to the docs, run gulp docs-watch to watch changes to files in _docs/ and rebuild your local copy of the documentation into docs-local/.

Gulp tasks are set up to save minified, distributable framework assets in dist/. Whenever you're committing changes to the framework, you should always include updated dist/ files in your commits.

However, documentation-related gulp tasks do not save distributable files to a tracked folder in the repo (docs-local/ is intentionally included in the project's .gitignore file). Commits for documentation-related changes should only include changes to files in _docs/; changes to production-ready documentation files (in docs/) are only made when new tags are released.

Gulp config options

Some key settings used in the framework's gulpfile are configurable via your gulp-config.json file. Available settings and their default values are listed below:

Option Default Description
sync false Whether or not BrowserSync should be initialized when gulp watch is run.

If you'd like to automatically spin up a virtual test server when gulp watch is run and auto-refresh your browser when changes are made, set this to true.
syncOptions
{
  "server": {
    "baseDir": "."
  },
  "startPath": "/examples"
}
Options to pass to BrowserSync when it is initialized during gulp watch. Will have no effect if sync is false.

See BrowserSync's documentation for available options. Function-based options are not supported.
examplesCSSKey "" If you'd like to enable premium webfonts on your local examples files, you can specify the URL of a Cloud.Typography CSS key here (e.g. https://cloud.typography.com/000000/000000/css/fonts.css).
examplesBaseURL "/examples" The baseurl setting to pass to Jekyll when building your local examples site. This value gets prepended to all internal links within the example files.
docSync false Whether or not BrowserSync should be initialized when gulp docs-watch is run.

If you'd like to automatically spin up a virtual test server when gulp docs-watch is run, set this to true.
docSyncOptions
{
  "server": {
    "baseDir": "."
  },
  "startPath": "/docs-local"
}
Options to pass to BrowserSync when it is initialized during gulp docs-watch. Will have no effect if docSync is false.

See BrowserSync's documentation for available options. Function-based options are not supported.
docBaseURL "/docs-local" The baseurl setting to pass to Jekyll when building your local documentation site. This value gets prepended to all internal links within the docs.

Gulp tasks

Our gulpfile contains a lot of functions and tasks--however, you likely won't (and probably shouldn't) use most of them directly. Listed below are the tasks you'll need to know about when working on the framework:

Task Description
gulp setup Runs a full build of the project--specifically, this task runs gulp default, gulp docs-local, and gulp examples.
gulp default The primary task for building out distributable framework assets. Handles components (gulp components) and Sass and JS linting, compilation, and minification (gulp css and gulp js). Saves distributable files to dist/.
gulp watch Watches changes to Sass files in src/scss/ and JS files in src/js/, and runs gulp css or gulp js, respectively, when those files change. Also watches changes to files in _examples/.
gulp components Copies over required files from third-party components out of node_modules/ into designated places within the project.
gulp css The primary CSS processing task for the framework. Lints and compiles Sass files in src/scss/, and saves minified distributable CSS to dist/css/. The framework's copyright header also gets prepended to the distributable CSS during this step.
gulp js The primary JS processing task for the framework. Lints JS files in src/js/, processes and saves out Bootstrap's source JS files into src/js/bootstrap/, and then concatenates + minifies JS files in src/js/, saving distributable JS to dist/js/. The framework's copyright header also gets prepended to the distributable JS during this step.
gulp docs-local The primary task for building out minified CSS and JS for the framework documentation, and for building a new local copy of the documentation site. The static documentation site will be built from _docs/ and saved to docs-local/.

Due to the way our documentation project is set up, and how Jekyll performs new site builds, we actually create minified CSS and JS within _docs/ (in _docs/static/) before building the local site, not during the jekyll build process. This means that, whenever changes are made to the documentation's styles or scripts, the full gulp docs-local task should always be run, so that the generated minified files get copied to your local docs-local/ directory for you to view and test the changes.
gulp docs-watch Watches changes to all files in _docs/ (except _docs/static/) and runs gulp docs-local) when changes are saved.
gulp examples The primary task for building a local set of example files to test the framework against. Files from _examples/ will be built out as a static site and saved to examples/.

Contributing

We highly encourage feedback and suggestions from the UCF web development community. If you'd like to submit a feature request or known bug, check out our contributing guidelines.

License

The Athena Framework is released under the MIT License. Included third-party assets (such as webfonts and JavaScript libraries) may be released under separate licenses.

Documentation for the Athena Framework is released as a derivative of Bootstrap 4 alpha.6's documentation under Creative Commons.