https://github.com/graphieros/qroll

Last synced: about 1 year ago
JSON representation

Host: GitHub
URL: https://github.com/graphieros/qroll
Owner: graphieros
License: mit
Created: 2023-02-04T15:15:42.000Z (over 3 years ago)
Default Branch: master
Last Pushed: 2023-09-30T12:17:37.000Z (over 2 years ago)
Last Synced: 2024-10-24T02:35:20.332Z (over 1 year ago)
Language: TypeScript
Size: 4.05 MB
Stars: 1
Watchers: 3
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

README

# Qroll

```
npm i qroll
```
## DOCUMENTATION
### Wrapper Parent

The library targets a parent DIV by its id.

Wrap all your content into a parent DIV with the id 'qroll-parent' and class 'qroll-main'
The slides will correspond to the first level DIV children of the parent.
The example below will produce 3 slides:

```

My first slide

My Second slide

My Third slide

```

Add options to the Parent wrapper using css classes:
- transition duration:
> qroll-transition-[duration] with possible duration values 300, 400, 500, 600, 700, 800, 1000

- show the vertical navigation:
> qroll-nav

- use infinite loop scrolling:
> qroll-loop

```

My first slide

My Second slide

My Third slide

```

### Navigation

The navigation tooltips will try to find the first h1, h2, h3 or h4 element of each slide, to show their text content inside the tooltip. If there are no h1, h2, h3 or h4 element on a slide, the information provided in the tooltip will default to the page index.

You can also customize the content of your tooltips by adding a few data properties to your children divs. In the example below, the first tooltip will use the data-title property, the other tooltips will use the h2 element's content:

```

My first slide

My Second slide

My Third slide

```

You can also customize the css of each tooltip, using a data-tooltip-css property:

```

My first slide

My Second slide

My Third slide

```

### Meta tags management
You can set up meta tags (title and description) for all your main slides (not on horizontal slides), that will be applied on the HTML head when a slide gets into focus, so that each slide be treated as a separate page.

```

Slide 1

Slide 2

Slide 3

```

### Carousel

Children can become carousels by adding the following css classes:

```

My Second slide

My Third slide

```

### UI Components

#### Inner carousels

You can include a carousel component into a slide, by adding the following css classes to a slide's child div:

```

My inner carousel

My inner carousel paragraph 1

My inner carousel paragraph 2

My inner carousel paragraph 3

Slide 2

```
Inner carousels have an auto sliding feature you can activate adding a few data-attributes to the inner carousel div.

You can control sliding direction (defaults to right on horizontal carousel, and down on vertical) and the timing (defaults to 5000ms).
The activation of the auto-sliding feature will display a pause / play button on the top left of the carousel, allowing users to stop and start the auto sliding.

Horizontal carousel component:

```

My inner carousel

My inner carousel paragraph 1

My inner carousel paragraph 2

My inner carousel paragraph 3

Slide 2

```

Vertical carousel component:

```

My inner carousel

My inner carousel paragraph 1

My inner carousel paragraph 2

My inner carousel paragraph 3

Slide 2

```

#### Dialog

Qroll provides a ready-made wrapper for the native HTML dialog element, to help you set up easy modals.
Dialogs require the following:
- to be placed at the same level as first children of the main parent
- a "qroll-dialog" class
- a unique data-id attribute

You can also provide a title, that wil be displayed in the header of the dialog, and specify if you wish to display a close cross button on the top right of the modal. Finally, you can provide a set of css classes into the data-css-classes attribute, and refer to these classes in your own css.

```

My slides

Slide 2

Warning, you are awesome !

```

Dialogs can be open from anywhere in your application by calling the qroll.openDialog() interface, passing it the id as an argument. It can be used inline:

```

My slides

Slide 2

Am I awesome ?

Warning, you are awesome !

```

...or in your own javascript file:

```

const triggerButton = document.getElementById("triggerButton");
triggerButton.addEventListener("click", () => {
qroll.openDialog("myDialog")
});

```

Reversely, a dialog can be closed from your application:

```

const triggerButton = document.getElementById("triggerButton");
triggerButton.addEventListener("click", () => {
qroll.openDialog("myDialog");
setTimeout(() => {
qroll.closeDialog("myDialog");
}, 3000);
});

```

You can add a carousel inner component into your dialog element (horizontal only):

```

My slides

Slide 2

Am I awesome ?

Awesome 1

Awesome 2

Awesome 3

```

#### Charts

Qroll provides a set of minimalist charts to complement your slides on the go with cool graphs that are easy to set up.
Add the "qroll-chart" class to a div inside a slide, and use data attributes for all the options.
You can include your own set of colors. If not, great default colors will be applied.

The dataset passed into data-x-values and data-y-values uses JSON format.

1. Line charts / Bar charts
They work exactly the same, just change the data-type to "line" or "bar", all the other required data-attributes are identical.

```

My line chart

Slide 2

Slide 3

```

2. Donut chart

```

My Donut chart

div
style="max-width: 600px; margin:0 auto"
class="qroll-chart"
data-type="donut"
data-title="title"
data-subtitle="This is a subtitle"
data-total="true"
data-total-label="Total"
data-tooltip="true"
data-x-values='[
{
"name" : "Blue serie",
"data" : 10
},
{
"name" : "Red serie",
"data" : 20
},
{
"name" : "Orange serie",
"data" : 30
},
{
"name" : "Green serie",
"data" : 5
},
{
"name" : "Purple serie",
"data" : 3
},
{
"name" : "Indigo serie",
"data" : 10
}
]'
>

Slide 2

Slide 3

```

3. Thermometer Gauge

```

My Gauge chart

Slide 2

Slide 3

```

If your data gets updated, you will need to refresh the charts.
For now the way to proceed is slightly barbaric, yet effective:

```

// refresh charts after data update

function refreshCharts() {
const charts = document.getElementsByClassName("qroll-chart");
Array.from(charts).forEach(chart => {
chart.innerHTML = "";
});
qroll.updateCharts();
}

refreshCharts();

```

### Menu

Qroll provides a ready-made menu you can choose to add to your application.
Just set up an empty div at first child of the main parent element, with the following attributes:

```

My slide 1

My slide 2

```
The data-auto attribute will create menu items based on your main slides, and link to them.
You can also provide additional links (or only use these), by adding the data-additional-links attribute, and provide an array of links.
This is also the place where you can link to a specific horizontal slide index (for example: slide 3 at horizontal index 2):

```

My slide 1

My slide 2

```

As for styling the menu, you can provide your own css classes through the data-css-classes attribute, or target the following classes:

```

.qroll-main-menu-backdrop {}
.qroll-main-menu-body {}
.qroll-main-menu-item {}
.qroll-main-menu-item--selected {}
.qroll-main-menu-link {}
.qroll-main-menu-title {}
.qroll-main-menu-trigger-button {}

```

### Basic UI Elements

#### Buttons, inputs, textareas & selects
A range of ready made css classes allows you to style your buttons & basic form elements directly in your HTML.

```

CLICK

```

Here is a list of available classes for these items:

| Class | Description | Examples |
| ----- | ----------- | -------- |
| bg | Background: add any color type after the dash | bg-white, bg-#FFF |
| text | Text color: add any color type after the dash | text-white, text-#FFF |
| radius | add a number after the dash. Corresponds to px | radius-6 |
| rounded | sets border radius to ideal rounded shape | rounded |
| outline | provide a number and a color | outline-1-#FFF |
| h | Height: provide a number, corresponds to em | h-1, h-0.5 |
| ma | Margin all : provide a number, corresponds to em | ma-1, ma-0.2 |
| mx, my, mt, mr, mb, ml | Specified margin, provide a number, corresponds to em | mx-1, my-0.2, mt-3, mr-2, mb-0.5, ml-2 |
| pa | Padding all: provide a number, corresponds to em | pa-1, pa-0.5 |
| px, py, pt, pr, pb, pl | Specified padding, provide a number, corresponds to em | px-1, py-0.2, pt-3, pe-2, pb-0.5, pl-2 |

### Interface

Qroll exposes a few methods you can control:

1. Slide up

```

qroll.slideUp();

```

2. Slide down

```

qroll.slideDown();

```

3. Slide to index

```

// go to first slide
qroll.slideToIndex(0);

// go to second slide of horizontal carousel page
qroll.slideToIndex(1,1);

```

4. Refresh everything. If your content has changed as a result of SSR, you'll need to run the library again to apply the changes on the new content.

```

qroll.refresh();

```

5. Get current slide index (number)

```

qroll.getCurrentSlideIndex();

```

6. Get slides as an array with the following data type:

```
{
element: HTMLElement;
hasCarousel: boolean;
index: number;
title: string;
}
```

```

qroll.getSlides();

```

# Integration in main frameworks

## Vue

### Vue 2 (single page application)

- add qroll.js and style.css into the public folder
- in public/index.html directly include the script tag referring to qroll.js:

```

- Place the main parent div inside App.vue:

```

```
... and you are good to go :)

## Nuxt 3

Add qroll's style.css into the assets/css folder
Add qroll scripts into the public folder (both qroll.umd.cjs and qroll.umd.cjs.map)

- nuxt.config.ts: if there is only one page in your application.

```
export default defineNuxtConfig({
app: {
head: {
script: [
{
src: /qroll.umd.cjs,
body: true,
defer: true,
crossorigin: ""
}
]
}
},
css: ['@assets/css/style.css']
})

```

- Or directly in the head of your vue file, if your application contains several routes. Add the script to every head of every vue file using the library.

- Place the main parent div inside your index.vue file. Don't forget to add data-delay (ms) and data-nuxt attributes.
data-delay will show a spinner while the script is running to put your slides into shape, whild data-nuxt="true" will make sure the script runs after the HTML is displayed.

- There are 2 types of loader icons you can use:
1. "spin" (rotating arrows, default icon)
2. "dots" (alterning animated dots), use data-loading-icon="dots"

```

// your code here
// if you need to restart qroll after a page hydration, you can call window.qroll.restart(), but no need to do that on the first load.

```

## Other scripts tampering with class names
- Some other libraries you may use could tamper with class names. You can be extra safe by adding the class "qroll-slide" to all direct children of the "qroll-parent" div.

https://github.com/graphieros/qroll

Awesome Lists containing this project

README

My first slide

My Second slide

My Third slide

My first slide

My Second slide

My Third slide

My first slide

My Second slide

My Third slide

My first slide

My Second slide

My Third slide

Slide 1

Slide 2

Slide 3

Carousel slide 1

Carousel slide 2

Carousel slide 3

My Second slide

My Third slide

My inner carousel

Slide 2

My inner carousel

Slide 2

My inner carousel

Slide 2

My slides

Slide 2

My slides

Slide 2

My slides

Slide 2

My line chart

Slide 2

Slide 3

My Donut chart

Slide 2

Slide 3

My Gauge chart

Slide 2

Slide 3

My slide 1

My slide 2

My slide 1

My slide 2