Project README

README

Summary

See UI Library site for documentation, and UI and code examples.

Project Setup for Development

Clone the project.
Ensure the Ruby version specified in .ruby-version is installed.
Run ./script/bootstrap to install the project dependencies.
Use middleman to run the development server.
use middleman build to build the project into the <project>/build directory.
If deployment to your dev server is desired, consult with Hosting (Andy) to have your dev environment configured.

Default Deploy Process

The project on Jenkins is entitled flexmls-ui-library. Whenever code is pushed to master, the site will be built and deployed to http://design.dev.fbsdata.com.

If you need to deploy code from a branch other than master, do so locally, or - From the Jenkins job page, Choose Build with Parameters. - In the GIT_BRANCH parameter, enter the Branch/SHA1/Tag which you'd like to have built. - Make sure the RELEASE_SITE box is checked.

Production Deploy Process

When you're ready to run a production release: - On the main Github repository page, click the Releases link (in the top panel alongside # commits, # branches, and # contributors - In the top right, click Draft a new release - enter the tag for the version you're about to publish. This should match whatever is in the VERSION file - If you're publishing from a branch other than master, specify the correct target in the box next to the tag version - Supply a human-friendly title - Click the big, green "Publish Release" button

A Jenkins build will be kicked off for the correct revision with the RELEASE paramter checked.

CDN Resources

The assets reside at //cdn.assets.flexmls.com/flexmls-ui/ and generally have names like:

flexmls-ui-<fingerprint>.(js|css)

Adding the correct version to your project will likely be already set up, but see the Use in FBS Projects section below for further details.

Project Versioning Strategy

(This section needs work and input from others to ensure accuracy and flesh it out.)

Have a branch for each new release until work is done on it.
Branches other than master can be deployed so the new version can be worked with from the CDN.
Merge the new version branch into master only after it has been verified to be correct.
Create a tag for the version in the format of vX.X.X, eg. v0.1.1 and push it to GHE.

Flexicons

The flexicons have become part of the UI Library project. Here are the steps to integrate the icon files into this project:

Replace /source/flexicons directory with the contents of the .zip file provided by Design.
Copy and rename /source/flexicons/style.css to /source/assets/styles/1_theme/_flexicons.scss.
Copy /source/flexicons/fonts/* to /source/assets/styles/fonts/*.
That's it.

Scoped CSS Version

An additional version of the CSS portion of the UI Library is now available alongside the normal "unscoped" version. This version can be used to target specific parts of a page by wrapping the targeted portion in the scoping class: .flexmls-ui-scope, while leaving the remainder of the page unchanged.

This scoped version is automatically generated when building the project and is listed in the asset manifest as scoped-flexmls-ui.css.

Use in FBS Projects

This is how the UI Library is used in FBS projects.

Flagship

Update the version in server/assets/flexmls-ui.json to the version of the UI Library you want to use.
During development, you can run rake asset_manifest to retrieve server/assets/manifest.json.
The asset_manifest task is also included in the build and sync tasks.
Include the asset files in the page you're working on using the cssTag and sciptTag functions in server\util.js passing in true for the last parameter named useCdn for each function.

Rails Projects

Add the spark_api_rails gem to the project.
Add the following lines to config/application.rb ensuring the version matches the UI Library version you want to use.

config.flexmls_ui.enabled = true
config.flexmls_ui.version = '0.4.2'

Include the CDN versions of flexmls-ui.css and flexmls-ui.js in the pages or layouts where you want to use the UI Library.

<%= stylesheet_link_tag(shared_asset_uri('flexmls-ui.css')) %>
<%= javascript_include_tag(shared_asset_uri('flexmls-ui.js')) %>

Run rake flexmls_ui:update_manifest task which will retrieve and add config/flexmls-ui-manifest.json to the project.
Be sure to check in the changes to flexmls-ui-manifest.json when committing updates to the project.

Generic Usage

Navigate to rweb1:/home/httpd/app_assets/flexmls-ui/prod/current/public/manifest/
Choose a version (usually the latest version) and change to its directory.

[flexadm@rweb1.flex 0.5.1]$ pwd
/home/httpd/app_assets/flexmls-ui/prod/current/public/manifest/0.5.1

View the contents of the manifest.json file which will be something like this:

[flexadm@rweb1.flex 0.5.1]$ cat manifest.json
{"version":"0.5.1","assets":{"flexmls-ui.css":"flexmls-ui-dbdccb3a.css","flexmls-ui.js":"flexmls-ui-5ef9f400.js"}}

Append a fingerprinted filename to https://cdn.assets.flexmls.com/flexmls-ui/ to form a URL like this: https://cdn.assets.flexmls.com/flexmls-ui/flexmls-ui-dbdccb3a.css
Use the URLs like the one above as appropriate in your project.

Local Docker Development

Clone the project locally
Modify the left hand side of the volumes field to reflect the directory where you cloned the project. This mounts your local directory inside the container. Depending on what platform you are on it may require slightly different format, the below instance is on MacOS.

volumes: 
  - /Users/coryrolstad/source/flexmls-ui-library:/opt/app

Issue a "docker-compose up" command from the command line and if everything worked properly, the image will be built, mount your local development directory, and will start the middleman application.
When the application has started up goto http://localhost:4567/ and you should see the Flex UI Library web page, any development changes you make locally are reflected appropriately with the hotreload functionality.