@valencyhq/valency
v0.1.5Valency
๐ค What is Valency?
Valency is a tool to manage and serve design assets.
- Design assets managed with Valency are served for use over a CDN.
๐ฆ Install
npm install @valencyhq/valency --save
Table of Contents
๐งช Quick start
<!DOCTYPE html>
<html lang="en">
<title></title>
<script src="https://unpkg.com/@valencyhq/valency"></script>
<body>
<img data-valency="cat-dog" />
<script>
var valent = new Valency({
uid: 'your user ID',
project: 'your project ID',
library: 'Your library ID',
})
valent.replace()
</script>
</body>
</html>
๐จโ๐จ Usage
The following ways you can use assets served by Valency.
๐ Client-side JavaScript
1. Install
Note: If you intend to use Valency with a CDN, you can skip this installation step.
Install with npm.
npm install @valencyhq/valency --save
Or just copy valency.js or valency.min.js into your project directory. You don't need both valency.js and valency.min.js.
2. Include
Include valency.js or valency.min.js with a <script>
tag:
3. Use
To use an icon on your page, add a data-valency attribute with the icon name to an element:
<img data-valency="man-dog" />
<object data-valency="man-dog"></object>
<div data-valency="man-dog">Your background image goes here</div>
4. Setup & Replace
Setup Valency with your credentials. Call the valency.replace()
method:
<script>
var valent = new Valency({
uid: 'Your user ID',
project: 'Your project ID',
library: 'Your library ID',
})
valent.replace()
</script>
All elements that have a data-valency
attribute, their src
or data
atrribute will be replaced with the assset's URL corresponding to their data-valency
attribute value.
See the API Reference for more information about valency.replace()
.
๐ SVG Sprites & Icons
Valency serves icons packed into a single SVG sprite.
If an icon in a icons library is not a vector
(PNG or JPG)
, it gets converted toSVG
, then packed into the SVG sprite. For Valency to serve SVG Icon sprite for a library, the library's category must beicon
1. Usage
<svg
data-valency="icon-name"
width="24"
height="24"
fill="none"
stroke="currentColor"
></svg>
<!-- you can also use i tag -->
<i data-valency="icon-name"></i>
Use data-valency-lib
to set a library name if you don't want to use the default.
<svg
data-valency="icon-name"
data-valency-lib="icons-library-name"
width="24"
height="24"
fill="none"
stroke="currentColor"
></svg>
<i data-valency="icon-name" data-valency-lib="icons-library-name"></i>
โ๏ธ React
There is a wrapper library for React, have a look at react-valency.
๐ Figma
Valency is available as a Figma plugin. To use the plugin, log in to your Figma and install it. Get it now!
โ๏ธ API Reference
valency.get(assetName, config?)
Returns a URL to the provided assetName
.
If
config
argument is provided, it is used to generate the link instead of the default configuration set at instance ofValency
.
valency.get() shorthand properties
Valency provides convenient shorthand properties to Valency.get()
which provides an intuitive way to get an asset's URL.
The shorthand format goes like this:
valent.asset.<assetName>.url
valent.asset.<yourLibraryId>.<someAssetName>.url
valent.asset.<yourProjectId>.<yourLibraryId>.<someAssetName>.url
valent.asset.<yourUserId>.<yourProjectId>.<yourLibraryId>.<someAssetName>.url
Let's show some sample Valency.get()
usage with it's shorthand equivalent.
const valent = new Valency({
uid: '9825624020',
project: 'PsSBtkjlQys',
library: 'LIB_i7J',
})
/** ๐ EXAMPLE 1 **/
valent.get('blondeAvatar')
/**
* Shorthand ๐ค
* valent.asset.<assetName>.url
*/
valent.asset.blondeAvatar.url
// returns https://cdn.valency.design/9825624020/PsSBtkjlQys/LIB_i7J/blondeAvatar
/** ๐ EXAMPLE 2 **/
valent.get('03886')
/**
* Shorthand ๐ค
* valent.asset.<assetName>.url
*/
valent.asset['03886'].url
// returns https://cdn.valency.design/9825624020/PsSBtkjlQys/LIB_i7J/03886
/** ๐ EXAMPLE 3 **/
valent.get('latinoAvatar', {
library: 'LIB_3D_avatars',
})
/**
* Shorthand ๐ค
* valent.asset.<libraryID>.<assetName>.url
*/
valent.asset.Lib_3D_avatars.latinoAvatar.url
// returns https://cdn.valency.design/9825624020/PsSBtkjlQys/LIB_3D_avatars/latinoAvatar
/** ๐ EXAMPLE 4 **/
valent.get('spaceship', {
library: 'LIB_i3m',
project: 'pNASA',
})
/**
* Shorthand ๐ค
* valent.asset.<projectID>.<libraryID>.<assetName>.url
*/
valent.asset.pNASA.LIB_i3m.spaceship.url
// returns https://cdn.valency.design/9825624020/pNASA/LIB_i3m/spaceship
/** ๐ EXAMPLE 5 **/
valent.get('Mast Head.png', {
library: 'LIB_mcq',
project: 'pMaterial',
uid: '03786',
})
/**
* Shorthand ๐ค
* valent.asset.<userID>.<projectID>.<libraryID>.<assetName>.url
*/
valent.asset['03786'].pMaterial.LIB_mcq['Mast Head.png'].url
// returns https://cdn.valency.design/03786/pMaterial/LIB_mcq/Mast Head.png
valency.replace(config?, document?)
All elements that have a data-valency
attribute, their src
atrribute will be replaced with the assset URL corresponding to their data-valency
attribute value.
If
config
is provided, it's merged with the base configuration. Note that whatever options contained in theconfig
object takes precedence over the base configuration when they're merged together.
If
document
is provided, it carries out replace on it instead ofwindow.document
.
valency.loadSprite(config?)
Loads the SVG sprite of a library into the DOM
.
If
config
is provided, it's merged with the base configuration. Note that whatever options contained in theconfig
object takes precedence over the base configuration when they're merged together.
valency.getConfig(otherConfig?)
Returns configuration object.
If
otherConfig
is provided, it's merged with the base configuration. Note that whatever options set inotherConfig
takes precedence over the base configuration when they're merged together.
valency.setConfig(otherConfig)
Use to globally update configuration.
๐จโ๐ง Contributing
For more info on how to contribute please see the contribution guidelines.
Caught a mistake or want to contribute to the documentation? Edit this page on Github
๐งพ License
Valency is licensed under the MIT License.
Metadata
- Apache-2.0
- Whatever
- ahkohd
- released 5/11/2021