Working with the AlloyUI project
Liferay bundles AlloyUI with the portal, as it’s used throughout the portal and core portlets. Conveniently, you can use AlloyUI in any project–it doesn’t have to run on Liferay. When you develop AlloyUI scripts and components for use in the portal, you can reuse them anywhere else. If you’re using AlloyUI outside Liferay, you might want to build it yourself.
Here are some other reasons why you might use a local AlloyUI installation or AlloyUI project build:
- Creating and testing your own AlloyUI component modules
- Using the latest AlloyUI project source code that is not yet released
- Using AlloyUI on a closed network
- Contributing and testing a fix or enhancement to AlloyUI
Let’s download AlloyUI and set it up for developing AlloyUI scripts and components locally.
Working with an AlloyUI Project Release Zip File
You can download any AlloyUI version as a
.zip file from https://github.com/liferay/alloy-ui/releases. The file contains the following files and folders:
alloy-[version]/ - AlloyUI project root directory
build/ - Contains the AlloyUI and YUI modules used in Liferay
demos/ - Contains basic examples of the AlloyUI components
src/ - Contains the source code of the AlloyUI modules
.alloy.json - Specifies how to build the modules
LICENSE.md - Defines AlloyUI’s the license agreement
README.md - Explains the AlloyUI project
As you did in the initial example, the first thing you’ll call is AlloyUI’s
aui-min.js seed file, in your
alloy-[version]/build/aui/ folder. For example, if your AlloyUI project root directory is
/home/joe.bloggs/alloy-2.0.0/, you’ll refer to the seed file like this:
Likewise, make sure to specify your local bootstrap seed file as well:
Go ahead and replace the remote seed file references from the example HTML file we used at the beginning of this chapter with references to your local seed files. Except for the paths to your seed files, your HTML content should look similar to this:
<input type="text" id="some-input" />
<span id="counter"></span> character(s) remaining
The figure below shows what your web page should look like.
Figure 12.3: Using AlloyUI on any HTML page is easy. Try out AlloyUI’s character counter on your own page using the code above.
Great! Now you know how to use a local set of the AlloyUI tag libraries. Next, we’ll show you how to work with the AlloyUI source project. You’ll learn how to build the project so you can experiment with the latest AlloyUI code whenever you want.
Working with the AlloyUI Project Source
You may want to work with the latest cutting-edge AlloyUI code from time to time. Liferay makes it easy do get your hands on. We use a public GitHub project named alloy-ui to store and share the latest AlloyUI code. You can download the code so that you can build it and try it locally. You can also leverage the alloy-ui project to create some AlloyUI modules of your own. We’ll show you just how easy it is to install the project and use it.
In this section, we’ll demonstrate the following:
- Installing the required software for the AlloyUI project
- Installing the alloy-ui project
- Building the project
- Packaging the project in a distribution and using that distribution
Let’s get started by installing AlloyUI’s dependencies.
Setting Up AlloyUI’s Required Software
The alloy-ui project depends on the following software:
- Node.js is a platform for building applications.
- Ruby is used in the alloy-ui project for downloading other software packages.
- Compass is an open-source CSS authoring framework.
- Sass stands for Syntactically Awesome Stylesheets. It is a scripting language used for specifying CSS.
Let’s install Node.js first. You can download it from http://nodejs.org/. Linux, OS X, or UNIX users can download its source in a
.tar.gz file, unzip it, un-tar it, and build it per the instructions in its
README.md file. Windows users can download the
.msi installer file and run it.
Warning: On Windows, only install to locations that have UNIX-friendly paths. Paths like
C:\Program Files (x86) that contain space characters and parentheses can prevent software from working properly.
You can download Ruby from https://www.ruby-lang.org. Alternatively, on Windows, you can download RubyInstaller from http://rubyinstaller.org/ and use it to install Ruby. After installing Ruby, execute the following command from your terminal to get its latest updates:
gem update --system
Now, let’s use Ruby’s gem command to install Compass and Sass. Conveniently, Sass comes bundled with Compass. To install both of them, simply execute the following command:
gem install compass
Great! You’ve installed all of the software applications that the alloy-ui project requires. Next, let’s get our hands on the alloy-ui project.
Installing the AlloyUI Project
Liferay’s AlloyUI developers and AlloyUI community members contribute code to the alloy-ui project on GitHub. To access the alloy-ui project and install it locally, you’ll need an account on GitHub and the Git tool on your machine. Visit https://github.com/ for instructions on setting up the account and see http://git-scm.com/ for instructions on installing Git.
Here are some simple steps for forking the alloy-ui project on GitHub and installing the project locally:
Go to the AlloyUI project repository at https://github.com/liferay/alloy-ui.
Click Fork to copy Liferay’s alloy-ui repository to your account on GitHub.
In your terminal or in GitBash, navigate to the location where you want to put the alloy-ui project. Then download a clone of the repository by executing the following command, replacing
username with your GitHub user name:
git clone firstname.lastname@example.org:username/alloy-ui
Now you have your own personal copies of the project in GitHub and on your local machine. Before you start building the project, let’s set it up with the
2.0.x branch. AlloyUI 2.0 is the version used by Liferay Portal 6.2.
Navigate to your new alloy-ui directory in GitBash by running
To download Liferay’s alloy-ui branches, you must first associate a remote branch to Liferay’s alloy-ui repository and then fetch all of branches via that remote branch:
git remote add upstream email@example.com:liferay/alloy-ui.git
git fetch upstream
Lastly, create your own branch named
2.0.x based on Liferay’s
2.0.x branch, by executing the following command:
git checkout -b 2.0.x upstream/2.0.x
Great! Now that you have the
2.0.x branch checked out, we can install and initialize the project’s remaining dependencies. Follow these steps:
Install the global dependencies (exclude using
[sudo] on Windows):
[sudo] npm install -g grunt-cli shifter yogi yuidocjs phantomjs
Then install the local dependencies:
Lastly, the alloy-ui project has a special target called
init that clones and updates the GitHub software projects on which alloy-ui depends. These projects include yui3, ace-builds, alloy-bootstrap, alloy-apidocs-theme, and alloyui.com. Initialize these projects for alloy-ui by executing this command:
Alright! You have the alloy-ui project and all of its dependencies. Next, we’ll build AlloyUI.
Building the AlloyUI Project
The alloy-ui Project Grunt Targets
|Target ||Command ||Description |
|Builds YUI and AlloyUI together |
|Builds YUI only |
|Builds AlloyUI only |
|Builds and imports Bootstrap’s CSS |
Let’s build everything by executing the following command:
On successfully executing each of these commands, Grunt reports this message:
Done, without errors. Well done!
Note, to build a single AlloyUI module, you can execute the following (replace
aui-module-name with the module’s name):
grunt build:aui --src src/aui-module-name
When you’re ready to try out your locally built version of AlloyUI, you can package it up and use it. We’ll do that next.
Using Your Locally Built AlloyUI Distribution
Building a release distribution of your alloy-ui project is easy. And it’s just as easy using your distribution in your web pages. We’ll do it together.
To create your distribution
.zip file of AlloyUI, execute the following command:
This creates zip file
alloy-[version].zip. Unzip this file to an arbitrary location.
You can reference your AlloyUI distribution in your Liferay JSPs in the same manner we demonstrated in the section Working with an AlloyUI Project Release. That is, you reference AlloyUI’s
aui-min.js file as a seed file.
For example, you could specify the following seed file, replacing
/home/joe.bloggs/ with the path to your unzipped distribution.
It’s just that easy to use your very own cutting-edge copy of the AlloyUI code!