Pulsar

Pulsar is the User Experience and Interface framework for Jadu software.

Pulsar is a robust user interface framework with a collection of patterns, helpers and a user-focused design process with documented best practices that will help you to make beautiful user interfaces and amazing user experiences.

UI Goals

UX Goals

Getting Started

This is a quick guide to using Pulsar in a standalone project. This guide does not relate to Continuum products.

Download

PHP / Composer

Pulsar needs to be brought into your project as a dependency, for PHP projects we recommend using Composer.

composer install jadu/pulsar --save-dev --prefer-dist

This will install Pulsar to your /vendors directory. We’re going to assume you’re familiar with using Composer for this quick guide.

Pulsar has a lot of files, like tooling and tests, that aren’t strictly required for a working project, the --prefer-dist flag will use the .gitattributes file included within Pulsar to only bring in the essentials.

Direct download

Download a zipped archive of the Pulsar package and place it somewhere in your project directory. We recommend keeping Pulsar files self-contained somewhere like /path-to-project/pulsar.

https://github.com/jadu/pulsar/archive/develop.zip

Pulsar Fonts

Jadu’s chosen typeface is Proxima Nova, due to licensing restrictions this is not included in the Public GitHub repository.

There is a pulsar-fonts repository on Jadu’s GitLab, which can be pulled in via Composer or directly downloded. It should be placed as a sibling directory next to the Pulsar directory, so:

/your-project
    └── /pulsar
    └── /pulsar-fonts

or

/your-project
    └── /vendor
        └── /jadu
            └── /pulsar
            └── /pulsar-fonts

Directory Structure

Whether you use Composer or you directly clone the Pulsar GitHub repo, you’ll need to make sure these files and folders are made web-readable.

If you use Composer you can use a task runner like grunt-copy which runs the task on a successful composer install or composer update automatically, placing them into a directory of your choice.

/your-project
    └── /pulsar
        └── /images/*
        └── /libs
            └── /font-awesome/*
            └── /html5shiv/html5shuv.min.js
            └── /normalize-css/normalize.css
            └── /nwmatcher/src/nwmatcher.js
            └── /respond/dest/respond.min.js
            └── /select2/dist/css/select2.css
            └── /selectivizr/selectivizr.js
    └── /pulsar-fonts/src/*

Setup

HTML Setup

You will need to include Pulsar’s CSS and javascript into your pages, making sure the files point to the correct location of the Pulsar directory in your project.

<!DOCTYPE html>
<!--[if IE 7]><html lang="en" class="no-js ie7 lt-ie10 lt-ie8"><![endif]-->
<!--[if IE 8]><html lang="en" class="no-js ie8 lt-ie10 lt-ie9"><![endif]-->
<!--[if IE 9]><html lang="en" class="no-js ie9 lt-ie10"><![endif]-->
<!--[if gt IE 9]><!--><html lang="en" class="no-js"><!--<![endif]-->
<head>
    <title>Project Title</title>
    <meta charset="utf-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="description" content="">
    <meta name="viewport" content="width=device-width, initial-scale=1">

    <!--[if IE 7]>
    <link rel="stylesheet" type="text/css" href="/path-to-pulsar/css/pulsar-ie7.min.css" />
    <![endif]-->
    <!--[if IE 8]>
    <link rel="stylesheet" type="text/css" href="/path-to-pulsar/css/pulsar-ie8.min.css" />
    <![endif]-->
    <!--[if IE 9]>
    <link rel="stylesheet" type="text/css" href="/path-to-pulsar/css/pulsar-ie9.min.css" />
    <![endif]-->
    <!--[if gt IE 9]><!-->
    <link rel="stylesheet" type="text/css" href="/path-to-pulsar/css/pulsar.css" />
    <!--<![endif]-->

    <!--[if lt IE 9]>
    <script type="text/javascript" src="/path-to-pulsar/libs/html5shiv/dist/html5shiv.js"></script>
    <script type="text/javascript" src="/path-to-pulsar/libs/nwmatcher/src/nwmatcher.js"></script>
    <script type="text/javascript" src="/path-to-pulsar/libs/selectivizr/selectivizr.js"></script>
    <script type="text/javascript" src="/path-to-pulsar/libs/respond/dest/respond.min.js"></script>
    <![endif]-->

    <!--[if IE 7]>
    <link rel="stylesheet" type="text/css" href="/path-to-pulsar/libs/font-awesome/css/font-awesome-ie7.min.css" />
    <![endif]-->

    <script src="/path-to-pulsar/dist/js/bundle.js" id="main-js"></script>
    <script src="/path-to-pulsar/js/main.js"></script>

</head>
<body class="language-html">

    <!--
        MAIN LAYOUT GOES HERE
    -->

    <footer class="footer">
        <a href="#top"><i class="icon-circle-arrow-up"><span class="hide">Back to top</span></i></a>
        <a href="/jadu/version.php" class="branding-footer">Jadu Continuum</a> © 2018
    </footer>
</body>
</html>

Compiling Sass

You will need to create your own primary Sass file and import whichever pieces of Pulsar you need to achieve your UI. This also allows you to create your own Sass files and include them in the compiled output.

An example, ultra basic Sass file would look like this:

$ie-version: 12 !default;

// Third party plugins
@import '../libs/normalize-css/normalize.css';
@import '../libs/select2/dist/css/select2.css';

// Font awesome
$fa-font-path: '../libs/font-awesome/fonts';
$fa-css-prefix: 'icon';
@import '../../../../vendor/jadu/pulsar/libs/font-awesome/scss/font-awesome';

// Mixins
@import 'mixin.border-radius';
@import 'mixin.clear-fix';
@import 'mixin.content-box';
@import 'mixin.css-arrow';
@import 'mixin.hide-text';
@import 'mixin.inline-block';
@import 'mixin.label-variant';
@import 'mixin.media-queries';
@import 'mixin.mixins-to-organise';
@import 'mixin.responsive-utilities';

// Config
@import 'config.variables';

$font-path: '../../pulsar-fonts/src/';
@import 'config.fonts';

@import 'config.branding';

// Functions
@import 'function.math';
@import 'function.color-luminance';
@import 'function.pick-best-color';
@import 'function.color';

// Base colour palette
@import 'palette.base';

// Apply palette to components
@import 'config.theme';

// Structure
@import 'structure.grid';
@import 'structure.columns';
@import 'structure.scaffolding';
@import 'structure.type';
@import 'structure.forms';

// Layouts
@import 'layout.settings';
@import 'layout.sidebar';
@import 'layout.signin';
@import 'layout.tabs';

/* ------------------------------------------------------------------------- *\
    If you're theming Pulsar and want to include your own variables, colours or
    mixins you should @import them here.
\* ------------------------------------------------------------------------- */
// Third party libraries
@import 'libraries/library.colorpicker';

// Objects
@import 'objects/_object.box';
@import 'objects/_object.media';

// Components
@import 'component.actionsbar';
@import 'component.badges';
@import 'component.block-list';
@import 'component.breadcrumb';
@import 'component.button-groups';
@import 'component.buttons';
@import 'component.close';
@import 'component.datepicker';
@import 'component.daterange';
@import 'component.dropdowns';
@import 'component.edit-button';
@import 'component.flash';
@import 'component.footer';
@import 'component.forms';
@import 'component.icons';
@import 'component.input-groups';
@import 'component.labels';
@import 'component.lists';
@import 'component.loading';
@import 'component.login';
@import 'component.metadata';
@import 'component.modals';
@import 'component.navigation';
@import 'component.nav-list';
@import 'component.navbars';
@import 'component.pagination';
@import 'component.panels';
@import 'component.popovers';
@import 'component.progress-bars';
@import 'component.progress-lists';
@import 'component.range-slider';
@import 'component.remove-button';
@import 'component.search';
@import 'component.select2';
@import 'component.signin';
@import 'component.tab-help';
@import 'component.tab-panel';
@import 'component.tables';
@import 'component.datatables';
@import 'component.toggle-switch';
@import 'component.toolbar';
@import 'component.tooltips';
@import 'component.calendar';

/* ------------------------------------------------------------------------- *\
    If you're extending Pulsar and want to include your own layouts/modules etc
    you should @import them here.
\* ------------------------------------------------------------------------- */

// Utilities
@import 'utility.highlight';
@import 'utility.utilities';
@import 'utility.misc';
@import 'utility.states';

Your Sass task (using Grunt or similar) should accept a list of include paths, you can pass the path to your own scss directory as well as the Pulsar directories within /vendor (or wherever you choose to put it).

We choose to keep Pulsar scss files within /vendor as they shouldn’t be modified, you should add your own stylesheets, or open a pull request in the Pulsar repo to implement any required changes.

example: {
    options: {
        includePaths: [
            'scss',
            'vendor/jadu/pulsar/stylesheets',
            'vendor/jadu/pulsar-fonts/src'
        ]
    },
    ...

Core Elements

There are a handful of consistent user interface elements that should be included on all Pulsar UIs. These include:

Pulsar Core Elements - Greybox model

Base Layout

The base layout includes the core elements, and a full width content area which can contain whatever components the UI requires, such as forms, tables or something more complex.

Generally, all other layouts detailed here are extensions of the base layout.

Pulsar Base Layout - Greybox model

Base Layout with Sidebar Help

The sidebar help variation allows a column on the right hand side to contain help text to describe a user interface and provide more context to the user. This pattern is suitable for simple UIs where the tab__content is either a form or a table. For more complex UIs you may choose not to dedicate so much horizontal space for help text.

Pulsar Base Layout with Sidebar Help - Greybox model

Example

Pulsar Base Layout with Sidebar Help - Example

Settings Layout

The settings layout has a left hand column dedicated to form controls which control whatever elements may reside in the right hand column. A simple example is a document editor on the right, with the editing controls on the left.

Pulsar Settings Layout - Greybox model

Example

Pulsar Settings Layout - Example

Masterswitch Layout (shown with optional sidebar help)

The masterswitch layout has a single toggle switch that controls the enabled/disabled state of an entire user interface. Useful for patterns such as the integrations UI where a quick on/off switch needs to be provided.

Pulsar Masterswitch Layout - Greybox model

Example

Pulsar Masterswitch Layout - Example

Piano Layout

Shows a scrollable left hand column and a details area on the right. The piano layout allows users to quickly navigate through multiple items and still maintain the context of what other items exist in a list. Useful for messages (like GMail).

Pulsar Piano Layout - Greybox model

Example

Pulsar Piano Layout - Example

Reports Layout

Used exclusively for reporting UIs, this layout provides areas for report controls, charts and tabular data.

Pulsar Reports Layout - Greybox model

Example

Pulsar Reports Layout - Example