Monday, 6 February, 2017 UTC
Summary
Oracle JET, Oracle’s JavaScript toolkit for single page apps, includes over 80 components to help build enterprise JavaScript applications. But one thing JET doesn’t include is a set of icons – the argument being that different apps and teams will likely choose different icons. Luckily, it’s not too difficult to add Font Awesome to a JET app. If you’re using one of the starter apps without the Yeoman generator, have a look at Paul Thaden’s post on adding Font Awesome. In this post, I’ll show you how to add Font Awesome to a project created via the Yeoman generator.
For those who haven’t used it, Yeoman is a scaffolding tool designed to help kickstart new projects by running scripts called generators. Generators are often used to create opinionated starter apps with best practices and build scripts built in. The JET generator installs a sample app and includes a Grunt-based build system that can be customized as needed.
For those who haven’t used it, Yeoman is a scaffolding tool designed to help kickstart new projects by running scripts called generators. Generators are often used to create opinionated starter apps with best practices and build scripts built in. The JET generator installs a sample app and includes a Grunt-based build system that can be customized as needed.
Creating a New Project
Let’s start by creating a new JET project. Skip to the next part if you’d like to add Font Awesome to an existing app created via the generator. Assuming you already have Node.js installed (I’m using v6.9.5), let’s install some dependencies the JET generator requires as well as the generator itself.
npm -g install yo bower grunt-cli npm -g install generator-oraclejet
When those installs complete, you can verify the installation of the JET generator by showing its help. This is also a good way to get the template names if you forget them.
yo oraclejet --help
If everything is working correctly, you should see output like the following:
With the JET generator and its dependencies installed, we can now create a new JET project. I’ll use the web (default) version of the navdrawer template.
yo oraclejet my-jet-project --template=navdrawer
When that completes, we can cd into our new project directory and run a Grunt task named serve (which will run the build task too with default options). The build task will copy files to staging, compile SASS files, etc. – basically get the app into a state in which we can run it. The build task can be called independently with additional options, such as the target platform and theme.
The serve task will start a basic web server to serve the app’s files and then open the app in your default browser. Additionally, serve will setup file watchers on the source files and use LiveReload to refresh the browser when the source files are changed.
cd my-jet-project grunt serve
When the build script finishes you should see application open in a browser:
Return to the terminal and press ctrl + c to stop the Grunt serve task. With the new app in place, we are ready to add Font Awesome!
Adding Font Awesome
JET uses Bower as its front-end dependency manager so that’s how we’ll download Font Awesome.
bower install font-awesome --save
When that completes, you should see a new font-awesome directory under my-jet-app/bower_components.
The next step is to update the bowercopy.js file under my-jet-app/scripts/grunt/config so that the required Font Awesome files are coppied when the bowercopy task is run (more on that next).
Exactly how bowercopy.js is modified can vary depending on your needs. I wanted the Font Awesome files to be with my project’s CSS files so I added a new entry for 3rd party CSS. Note the leading comma, which separates the thirdParty entry at the bottom of the file from the thirdPartyCss entry being added.
,
thirdPartyCss:
{
options:
{
destPrefix: "src/css/libs"
},
files:
{
"font-awesome/css/font-awesome.css": "font-awesome/css/font-awesome.css",
"font-awesome/css/font-awesome.css.map": "font-awesome/css/font-awesome.css.map",
"font-awesome/css/font-awesome.min.css": "font-awesome/css/font-awesome.min.css",
"font-awesome/fonts/fontawesome-webfont.woff2": "font-awesome/fonts/fontawesome-webfont.woff2",
"font-awesome/fonts/fontawesome-webfont.woff": "font-awesome/fonts/fontawesome-webfont.woff",
"font-awesome/fonts/fontawesome-webfont.ttf": "font-awesome/fonts/fontawesome-webfont.ttf"
}
}
After updating bowercopy.js, we need to run the bowercopy task. This task copies files from bower_components to the destinations defined in bowercopy.js. As such, bowercopy only needs to be run when we add, change, or remove Bower components or make a change to bowercopy.js.
grunt bowercopy
Now that the Font Awesome files have been copied to our source code, we need to include the Font Awesome CSS file in our application. Open the index.html file found under my-jet-project/src in a text editor and add the following line in the head section under the comments related to “app specific styling”.
<link rel="stylesheet" href="css/libs/font-awesome/css/font-awesome.min.css" type="text/css"/>
With the CSS included, we can now use Font Awesome icons! As a demonstration, I’ll replace the icons used in the navigation menu with Font Awesome icons. This can be done by replacing the navData in the appController.js file found under my-jet-project/src/js with the following code (notice the fa-* classes).
// Navigation setup
var navData = [
{name: 'Dashboard', id: 'dashboard',
iconClass: 'oj-navigationlist-item-icon fa fa-tachometer fa-2x'},
{name: 'Incidents', id: 'incidents',
iconClass: 'oj-navigationlist-item-icon fa fa-fire fa-2x'},
{name: 'Customers', id: 'customers',
iconClass: 'oj-navigationlist-item-icon fa fa-users fa-2x'},
{name: 'About', id: 'about',
iconClass: 'oj-navigationlist-item-icon fa fa-info-circle fa-2x'}
];
Once the changes are saved, you should be able to run another grunt serve and when the application opens, it should look a little different (compare to the previous image from above).
In this particular case, I actually like the original icons a little more than the Font Awesome equivilents. But at least now we have hundreds of icons we can put to use… Happy coding!