Skip to content

drzzle-app/picazzo

Repository files navigation

npm NPM Travis (.com) branch GitHub closed issues GitHub last commit Twitter Follow


Picazzo is an open source front end framework that was created for websites built from the drzzle.app site builder.

See Docs

What's Included

β”œβ”€β”€ dist
|  β”œβ”€β”€ css
|  |  └── default.min.css
|  β”œβ”€β”€ icons
|  |  β”œβ”€β”€ css
|  |  |  β”œβ”€β”€ animation.min.css
|  |  |  β”œβ”€β”€ drzzle-codes.min.css
|  |  |  β”œβ”€β”€ drzzle-embedded.min.css
|  |  |  β”œβ”€β”€ drzzle-ie7-codes.min.css
|  |  |  β”œβ”€β”€ drzzle-ie7.min.css
|  |  |  └── drzzle.min.css
|  |  └── font
|  |     β”œβ”€β”€ drzzle.eot
|  |     β”œβ”€β”€ drzzle.svg
|  |     β”œβ”€β”€ drzzle.ttf
|  |     β”œβ”€β”€ drzzle.woff
|  |     └── drzzle.woff2
|  β”œβ”€β”€ js
|  |  β”œβ”€β”€ droplets
|  |  |  β”œβ”€β”€ accordion.min.js
|  |  |  β”œβ”€β”€ audio-player.min.js
|  |  |  β”œβ”€β”€ carousel.min.js
|  |  |  β”œβ”€β”€ content-slider.min.js
|  |  |  β”œβ”€β”€ countdown.min.js
|  |  |  β”œβ”€β”€ footer-nav.min.js
|  |  |  β”œβ”€β”€ form.min.js
|  |  |  β”œβ”€β”€ google-map.min.js
|  |  |  β”œβ”€β”€ image-gallery.min.js
|  |  |  β”œβ”€β”€ navigation.min.js
|  |  |  β”œβ”€β”€ section.min.js
|  |  |  β”œβ”€β”€ table.min.js
|  |  |  β”œβ”€β”€ tabs.min.js
|  |  |  └── video-player.min.js
|  |  β”œβ”€β”€ globals
|  |  |  └── picazzo.global.js.min.js
|  |  β”œβ”€β”€ modules
|  |  |  β”œβ”€β”€ jquery-2.2.4.min.js
|  |  |  └── jquery.mobile.custom.min.js
|  |  β”œβ”€β”€ picazzo.bundle.min.js
|  |  β”œβ”€β”€ picazzo.droplet.lib.js
|  |  β”œβ”€β”€ picazzo.droplet.lib.min.js
|  |  └── tools
|  |     β”œβ”€β”€ filter.min.js
|  |     β”œβ”€β”€ modals.min.js
|  |     β”œβ”€β”€ multi-step.min.js
|  |     β”œβ”€β”€ notifications.min.js
|  |     β”œβ”€β”€ pagination.min.js
|  |     β”œβ”€β”€ scrolling.min.js
|  |     └── tool-tips.min.js

Usage

NPM

npm install picazzo --save
// app.js

// default theme css
import 'node_modules/picazzo/dist/css/default.min.css';
// all droplets including dependencies (jQuery)
import 'node_modules/picazzo/dist/js/picazzo.bundle.min.js';

Browser (CDN)

Option 1 (All)

<html>
  <!-- default theme css -->
  <link rel="stylesheet" href="https://cdn.drzzle.app/themes/default.min.css">
  <!-- all droplets including dependencies (jQuery) -->
  <script src="https://cdn.drzzle.app/scripts/js/picazzo.bundle.min.js" charset="utf-8" defer></script>
</html>

Option 2 (Custom)

<head>
  <!-- default theme css -->
  <link rel="stylesheet" href="https://cdn.drzzle.app/themes/default.min.css">
  <!-- add jQuery dependencies -->
  <script src="https://cdn.drzzle.app/scripts/js/modules/jquery-2.2.4.min.js" charset="utf-8" defer></script>
  <script src="https://cdn.drzzle.app/scripts/js/modules/jquery.mobile.custom.min.js" charset="utf-8" defer></script>
  <!-- include Picazzo globals -->
  <script src="https://cdn.drzzle.app/scripts/js/globals/picazzo.globals.min.js" charset="utf-8" defer></script>
  <!-- use droplets as needed -->
  <script src="https://cdn.drzzle.app/scripts/js/droplets/accordion.min.js" charset="utf-8" defer></script>
  <script src="https://cdn.drzzle.app/scripts/js/droplets/table.min.js" charset="utf-8" defer></script>
</head>

Picazzo includes a Google Maps plugin. Depending on which JS option you use to install above you may need to create your own API Key to use it.

If using option 1 you will need to include this script before the bundle file. If using option 2 you will need to include this script only if you use the google-map plugin (as long as it's called before the map plugin file).

<script defer src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap" type="text/javascript"></script>

Development

Build Setup

# install dependencies
npm install

# serve with hot reload at localhost:8080
npm start
# build dist for production with minification for both picazzo the docs and library
npm run build

# build for production and view the bundle analyzer report
npm run build --report

Testing

To unit test vue components and droplet plugins run the following

npm run test:unit

Automation

Creating New Pages

npm run build:newpage

This will ask you a few questions like "name?", "full page layout or side bar?" and "path in the pages dir.", after which this will generate the needed files to get you started as well as create routing and searchable content. If you want this page to be a link in the sidebar, that needs to be done manually.

Creating a droplet page for example, you would use the path /droplets. Then add this to the layout/side-bar/links.json file.

Creating New Droplets

npm run build:newdroplet

Here you can specify the name and if it needs a js plugin or not and this task will go and add the new droplet to each theme as well as add the new vue files for the droplet in the correct locations.

Creating New Tools

npm run build:newtool

Tools are components that aren't necessarily droplets but could be used with them. Things like modals, tool tips, breadcrumbs, pagination etc. would be considered a tool. This script does what build:newdroplet does except puts the files in the tool location.

Creating New Themes

npm run build:newtheme

Here you just need to specify a name and this task will copy the default theme and create the new theme files for you. You just need to go and change the new LESS rules to how you wish manually of course.

Building distributable Picazzo JS droplet library

This task runs automatically for you but you can also run it manually:

npm run build:jsplugins

This will put together all of the js under droplets named "plugin.js" and compile/minify it into 1 distributable js file.

For building each js plugin separately into dist you will need to run the following command manually:

npm run build:jsplugins:separate

Creating routes

This always runs for you automatically when you create new pages, but if you prefer to make routes manually, you can add them in the src/router/routes.json file. Once you edit that file, this task should go and update the routes that vue reads from. If you want to manually regenerate the routes file you can run:

npm run build:routes

Build search

This will also run automatically for you whenever you edit or add any template in the pages/ folder (this includes running the npm run build:newpage command). What it does is recursively search through the pages/ folder for page information, makes that into a JSON file so that it can be easily searched. To manually run this step:

npm run build:search

Adding Sidebar Links

Our nested side bar links are templated using json from our src/layout/side-bar/links.json file. They can be nested as deep as desired. FYI if a link has children (aka it's a dropdown) then it's route property won't be needed. See below of example:

{
  "links": [
    {
      "text": "Some Drop Down Link",
      "children": [
        {
          "text": "Deeper Drop Down Link",
          "children": [
            {
              "text": "Some Deeper Sublink",
              "route": "/some-deeper-sublink",
              "children": []
            }
          ]
        }
      ]
    },
    {
      "text": "I am a link with no children",
      "route": "/some-route",
      "children": []
    }
  ]
}

In case you forget what page route your page is, see the src/pages.json file.

Adding new Icons

We use fontello to manage icons. You will need to grab the config file located at src/icons/config.json and import it in fontello.

After selecting/adding new icons, you just need to download and copy the new files and place them into ./src/icons/. There is a watcher in place on this icons directory that should auto run this command for you

npm run build:icons

This task will take the fontello icons/files from ./src/icons/ and minify them then place them in dist/. The icons page also auto generates it's content from the fontello config file.

LESS Breakdown

The styling for Picazzo the app is separated from everything else, those core LESS files are located in ./src/less/picazzo/ and are compiled by webpack. The themes on the other hand are different. Those are compiled into dist/ by gulp and their core files are located in ./src/less/themes/. You'll notice each droplet has a themes/ directory. This is in case the same droplet will need to look different in each theme, if they are not needed, they can be removed.

Themes exist to give droplets default styling. These styles can be overridden in the editor by users.

Maintainable CSS

We go by the maintainable CSS rules when writing css/less. Please make sure you are aware of these before contributing. You can read the documentation here: Read Docs

Versioning

Use the following npm command to bump the current version

npm version major | minor | patch

Further Vue documentation regarding this app

Picazzo docs is built with vue. For a detailed explanation on how things work, check out the guide and docs for vue-loader.