First Step

Last updated: 20 days ago

Learn how to set up an OrcaUI page, reference JS/CSS files in multiple ways, and explore a live CodePen demo. Let’s get started with the OrcaUI front-end framework!

First Step20 days ago

Before You Begin

The OrcaUI frontend framework adopts CSS3 and HTML5 standards, extensively utilizing their supported features. When previewing documentation, we recommend using modern browsers like Chrome, Firefox, and Edge that fully support CSS3 and HTML5 for optimal display.

Built with modern JavaScript, the framework employs various new features including ES6+. Before modifying the framework, ensure you're familiar with modern JavaScript fundamentals to better understand and utilize its capabilities.

DOCTYPE Declaration

The <!DOCTYPE> declaration must be the first line in your HTML document. You can use HTML4.01 type, which has less strict syntax requirements for tags and attributes, with good compatibility that allows mixing with HTML5 tags.

 
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

Alternatively, you can use the simpler HTML5 declaration, but should understand HTML5 specifications. See https://www.w3schools.com/html/ for details. Since HTML5 is the future web standard, we recommend using:

 
<!DOCTYPE HTML>

Viewport Meta Tags

The meta tags in the head section are crucial for responsive design. Here are the recommended tags from our framework (copy and paste ready):


<meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=0">
<meta name="mobile-web-app-capable" content="yes">
<meta name="theme-color" content="#000">
<meta name="format-detection" content="telephone=no, email=no, address=no">
<meta charset="utf-8">

For production websites, you may also want to add:


<link rel="manifest" href="/manifest.json">
<link rel="apple-touch-icon" href="/icons/apple-touch-icon.png">
<meta name="robots" content="index, follow">

CDN Usage

OrcaUI's core files orca.js and orca.css are hosted on NPM with unpkg CDN acceleration. Click here to access the repository.

To reference the latest version:

 
<link href="https://unpkg.com/orcaui/dist/css/orca.css" rel="stylesheet" type="text/css">
<script src="https://unpkg.com/orcaui/dist/js/orca.js" type="text/javascript" charset="utf-8"></script>
Or minified versions:
<link href="https://unpkg.com/orcaui/dist/css/orca.min.css" rel="stylesheet" type="text/css">
<script src="https://unpkg.com/orcaui/dist/js/orca.min.js" type="text/javascript" charset="utf-8"></script>

For specific versions (replace [version] with actual version number):


<link href="https://unpkg.com/orcaui@[version]/dist/css/orca.css" rel="stylesheet" type="text/css">
<script src="https://unpkg.com/orcaui@[version]/dist/js/orca.js" type="text/javascript" charset="utf-8"></script>
Or minified:
<link href="https://unpkg.com/orcaui@[version]/dist/css/orca.min.css" rel="stylesheet" type="text/css">
<script src="https://unpkg.com/orcaui@[version]/dist/js/orca.min.js" type="text/javascript" charset="utf-8"></script>

Since the framework supports component instantiation via attribute properties, initialization should occur immediately after page load. We recommend placing JS files at the bottom with onload:

 
<!DOCTYPE html>
<html>
<head>
    <link href="https://unpkg.com/orcaui/dist/css/orca.css" rel="stylesheet" type="text/css" >
</head>
<body>
Page content
<script src="https://unpkg.com/orcaui/dist/js/orca.js" type="text/javascript" charset="utf-8" onload="orca.init()"></script>
</body>
</html>

Check out this CodePen template:

ES Module Import

An alternative CDN approach is using ES modules (type="module"), which requires the esm format.

ESM files support two export styles: named exports (export {}) and default exports (export default).

For independent modules: import {module1,module2} from 'orca.esm.js'
For bundled usage: import orca from 'orca.esm.js'

 
<!DOCTYPE html>
<html>
<head>
    <link href="https://unpkg.com/orcaui/dist/css/orca.css" rel="stylesheet" type="text/css" >
</head>
<body>
Page content
  <script type='module'>
    import orca from 'https://unpkg.com/orcaui/dist/js/orca.esm.js';
    console.log(orca);
    //For independent modules: import {module1,module2} is preferred
  </script>
</body>
</html>

Example template on CodePen:

Local Node Environment

Step 1: Setup Environment

After setting up Node with webpack or rollup, install locally via:


npm i orcaui

Step 2: Module Import

While UMD format only supports full imports, ESM format supports both full and partial imports with native import/export support. We recommend ESM for Node environments.

Two ESM import approaches:

Approach 1: Full Import


import orca from './node_modules/orcaui/dist/js/orca.esm.js';
import './node_modules/orcaui/css/orca.css';
console.log(orca,orca.Popup)

Approach 2: Partial Import


//ESM automatically treeshakes unused modules
import {Popup,Dialog} from './node_modules/orcaui/dist/js/orca.esm.js';
import './node_modules/orcaui/css/orca.css';
console.log(Popup,Dialog)

Professional developers needing TypeScript and Less source files for integration/customization should download the src and types files from the resources section.

Standard HTML Structure

Combining the above, here's a standard HTML structure. Since pages load sequentially, we recommend placing CSS in the head and JS at the bottom (copy and paste ready):

 
<!DOCTYPE html>
<html>
<head>
    <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=0">
    <meta name="mobile-web-app-capable" content="yes">
    <meta name="theme-color" content="#000">
    <meta name="format-detection" content="telephone=no, email=no, address=no">
    <meta charset="utf-8">
    <title>Page Title</title>
    <meta name="keywords" content="page keywords" />
    <meta name="description" content="page description" />
    <link href="https://unpkg.com/orcaui/dist/css/orca.css" rel="stylesheet" type="text/css" >
</head>
<body>
Page content
<script src="https://unpkg.com/orcaui/dist/js/orca.js" type="text/javascript" charset="utf-8" onload="orca.init()"></script>
<script type='text/javascript'>
    document.addEventListener("DOMContentLoaded", function () {
    //JS content
    });
</script>
</body>
</html>

Example template on CodePen:

For simplified PC-only HTML5 pages:

 
<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8"/>
    <title>Page Title</title>
    <meta name="keywords" content="page keywords" />
    <meta name="description" content="page description" />
    <link href="https://unpkg.com/orcaui/dist/css/orca.css" rel="stylesheet" type="text/css" >
</head>
<body>
Page content
<script src="https://unpkg.com/orcaui/dist/js/orca.js" type="text/javascript" charset="utf-8" onload="orca.init()"></script>
<script type='text/javascript'>
    document.addEventListener("DOMContentLoaded", function () {
    //JS content
    });
</script>
</body>
</html>