2 4. Dynamics
athena edited this page 4 months ago

Dynamics

Introduction to dynamics

Jupiter's JavaScript file provides some powerful features. I prefer to organize these features into a category called "dynamics."

Since the bulk of Jupiter is its CSS file, I have separated the classes from the dynamic elements. Anything related to JavaScript will be put in this document.

Dynamic elements

These are elements that are programmatically added to the end of your document if they are not found.

There are only two dynamic elements: modals and notifications

You can disable this feature in the src/js/core/config.js file.

Loading screen

By now, you've likely noticed the loading screen when switching between pages. The primary purpose is to only show the document when the page is completely finished loading. This improves user experience by not allowing users to see your page being compiled, no matter how briefly.

If you want to use the loader, make sure your entire page content is wrapped in a div with an ID of #root. You also need to manually add the loading element to the top of your page (outside of #root).

If you're using the config.enable_app_configuration, though, the loader should only affect the non-UI-Shell content. This way, your user can navigate with the sidebar loading near instantly, since it's lightweight.

The reason we can't dynamically populate the loading element is because the loading screen is meant to be shown while the page is loading. If we were to populate the element dynamically, the loading screen wouldn't work.

Here is the default loading element:

<div class="j-loading"><div class="j-loader xl"></div></div>

If you don't want to use the loading element, remove it from your page. The #root element will still only show when the page is fully loaded. If you want to completely disable loading, simply add the class .vis to the #root element.


Let's add a loading screen to your document.

Right before the #root element, add the above .j-loading code.

When you reload, you should see a rotating loading animation and then the content.


Animation

Animations, like Anchors, use the Intersection Observer API to add the specified animation class to your <div>.

To get animations to work, they need to be enabled in config.enable_animations.

From there, you can apply the data-animate="animation_class" attribute to any <div> element.

You can find animation classes in the src/css/animation/ folder.

If you need an animation to start immediately regardless of if it is in view, you can add the data-animate-instant="true" attribute to the element.


Let's animate!

First, let's use the Vivus extension shipped with Jupiter.

In your .html file, add the following line below jupiterui.css:

<link rel="stylesheet" href="../extensions/Vivus/vivus.css" />

Now on the .container element, add the following attribute: data-animate="v-fade-in-up"

Reload the page.

You should see the content slightly scale up after the loading screen disappears.

Now, let's add a button beneath the content.

Below the <p> element, add the following:

<a href="#" class="j-button">Learn more</a>

We'll come back to the document in a minute.


Anchors

Anchors use the IntersectionObserverAPI to automatically style them when you scroll to a particular section.

To get anchors to work, they need to be enabled in config.enable_anchors.

"Section" was used intentionally. To properly setup anchors, you need to add a few attributes to your page elements.

For starters, your "sections" need to be <section> elements with an ID. This ID is important. On the same element, you need to add the data-anchor="true" attribute.

From there, on any <a> tag, you add the attribute data-anchor-for="section_id".

It will then add the .active class to the element. Some elements offer styling by default, like .j-tab-link.

Copy text

To get copy events to work, they need to be enabled in config.setup_copy_events.

You can apply the data-copy attribute to any <a> tag. This will copy the text specified in the attribute to the users clipboard.

Dynamic attributes

To make things easy for everyone, Jupiter uses attributes on HTML elements to perform DOM operations.

Jupiter supports a variety of attributes which modify certain elements. All the relevant dynamic attributes are listed below.

Background images

On any <div> element, you can apply the data-bg-img attribute. This value is the URL of the image you want. You can also apply the following attributes:

data-bg-img-size and data-bg-img-position

Note: if you add "???" to the beginning of the URL, it will append the domain you're working on.

For instance, if you have an element

<div data-bg-img="???/public/images/hero.png"></div>

And you're using the domain "jupiterui.com," the final URL will be: https://jupiterui.com/public/images/hero.png

Icons

You can apply the data-icon attribute to any <i> element. The value of this attribute is a key in the icons object in src/js/core/data.js file.

If you'd like to add more icons, we recommend copying the SVG code from

Dynamic accents

You can apply the data-randomize attribute to any <a> tag. This will attach a click event that randomizes the accent color.

Notifications

Attaching the data-notify attribute to any <a> tag will attach a click event that launches a notification. This attribute accepts a JavaScript object. You can learn more on the

Modals

You can apply the data-modal attribute to any <a> tag. This will attach a click event that launches a modal. You can learn more on the

Theme toggle

You can apply the data-toggle-theme attribute to any <a> tag. This will attach a click event that toggles between dark and light mode.

Theme icon

You can apply the data-theme-icon attribute to any <i> tag. This will add an SVG icon inside the HTML to distinguish between light and dark mode. On light mode, it will show a moon; dark mode will show a sun.

Theme text

You can apply the data-theme-text attribute to any <a> tag. This will replace the inner text depending on the theme and your value for config.theme_text. I.e.: "Dark mode" or "Light mode"


Let's add another button to the document.

Replace <a href="#" class="j-button">Learn more</a> with:

<div class="flex flex-row justify-c align-c">
    <a href="#" class="j-button">Learn more</a>
    <a href="#" class="j-button gray ml-1r" data-toggle-theme="true" data-theme-text="true"></a>
</div>

Reload.

The button should toggle between the dark and light theme!


Head's up: you can use the .skeleton class to simulate loading content. Example:

<div class="w-100p mw-400 mt-48">
    <div class="skeleton"></div>
    <div class="skeleton w-90p my-16"></div>
    <div class="skeleton w-80p"></div>
</div>

Next: 5. Color