Beautiful js components to go with your project.
Ink offers a great set of Javascript components to enrich your user interface, which are easy to implement, powerful and responsive. We made these components thinking of people who don't know JS but still need to include certain features on their web pages without help from a programmer, but there is also a deep core of JS code to explore, if you're so inclined.
Next, we'll detail each component, explain it as simply as we can, provide you with all the configuration details and also provide you with links to the deeper technical docs, in case you are a developer, looking for more power under the hood.
To get started, you need to include certain scripts which will make your components work. We suggest you place these in your document's <head>
and keep them all neatly organised. You will need to include:
You can load these components from Ink's CDN or from your local host, here's how you do it.
Code for loading from CDN
<script type="text/javascript" src="http://js.sapo.pt/js/ink.js"></script> <script type="text/javascript" src="http://js.sapo.pt/js/ink.myModule.js"></script> <script type="text/javascript" src="http://js.sapo.pt/js/autoload.js"></script>
Code for loading from your local host
<script type="text/javascript" src="./js/ink.js"></script> <script type="text/javascript" src="./js/ink.myModule.js"></script> <script type="text/javascript" src="./js/autoload.js"></script>
We'll remind you to load the correct modules for each component, using the local host method, in the documentation below. Just replace the given local host examples with the CDN URL above, if you prefer it.
If you have a better grasp of JS and do not want all components intitialized off the bat, then do not inclue autoload.js, and, instead, initialize each component by hand. You can refer to the technical documentation to see how each initialization is made.
The Gallery component provides you an easy way to show images in a "carousel" format.
Besides being a responsive component, it also allows you to set other configurations such as:
Want to know more?
Check the technical documentation.
The Modal Window component allows you to place content in the form of a dialog window that takes center stage and fades out the rest of your content, allowing you to focus attention on that content and even require a certain action from your users to dismiss, or interact with that window.
Ink's Modal Window component is basically a bit of HTML and a Javascript instruction, so it's really easy to use and very flexible, allowing you to easily add text, images, videos, iframes, you name it.
The Modal Window is also really easy to configure, like our other components, simply by using data-attributes. Let's see how to get started.
Before you begin, make sure you're including the necessary Javascript inside your <head>
, you'll need ink.js, ink.modal.js and autoload.js to initialize the module automatically.
Code
<script type="text/javascript" src="./js/ink.js"></script> <script type="text/javascript" src="./js/ink.modal.js"></script> <script type="text/javascript" src="./js/autoload.js"></script>
If you opted for not using the autoload feature, then you'll need to initialize the Modal component by hand. Simply include the following code, at the end of your page, before the closing <body>
Code
<script type="text/javascript"> new SAPO.Ink.Modal('#myModal'); </script>
First, you need to create two wrappers, by using two <div>
. The first one must have the .ink-shade
class, and takes care of darkening the background in order to make your modal window float above the rest of the page. The second one, inside the first, must have the .ink-modal
class, to take care of setting up your window.
The .ink-modal
wrapper is the configurable bit of the window, which you can change by using data-attributes. Let's look at just the most common one, for now, which allows you to fire up your window from another element, such as a link: data-trigger="#myModal"
, this ID (in the example "myModal"), will be targetted by the Javascript instruction which will render the window onscreen; you can change the ID to whatever suits your particular case. If you don't use this attribute, the modal window will simply be created on page load, which is actually something you may want, so all our data-attributes are optional.
There's a lot more you can configure with data-attributes, but let's stay with the basic for now and we'll give you a list of all the parameters and their values further ahead.
So, up to now, you have this:
Code
<div class="ink-shade> <div class="ink-modal" data-trigger="#myModal"></div> </div>
That is the skelleton for the modal window. To add some content, you can create three <div>
, one for each of the .modal-header
, .modal-body
and .modal-footer
elements, inside the .ink-modal
container. These are self-explanatory and you can add whatever you want inside them, such as headings, paragraphs, lists, images, videos, etc.
You'll need an interactive element to close your window, so Ink offers the .ink-dismiss
class, which you can add to pretty much anything: an anchor, a button, a piece of text or an image which, when clicked by the user, will cause the modal window to be dismissed. There is also a .modal-close
class which specifically renders a small "X" button in your modal window to keep up with the familiarity factor from general users. Add it to a button, together with the dismiss class, in your modal window's header element, for example.
Let's see what we have so far, then:
Code
<div class="ink-shade"> <div class="ink-modal" data-trigger="#myModal"> <div class="ink-header"></div> <!--Add a title and a close button here--> <div class="ink-body"></div> <!--Add some text and an image, or a form, here--> <div class="ink-footer"></div> <!--Add your submit button and a close button, here--> </div> </div>
Simple enough, right? Now you need a link or a button to fire up your modal window, just make sure it has the same ID as you defined before. In our case: "myModal"
Code
<button id="#myModal">Open My Modal</button>
Hint We suggest you add the .fade
class to both your .ink-shade
and .ink-modal
containers, to obtain a fade-in transition for your modal window. Why don't you hop over to our glorious glossary to get an overview of every available class in Ink?
So, without further ado, you can open the example window, and then, check out the example code below, by hitting the view code button.
As you can see in the example code above, there are several data-attributes you can use to configure your window. In our case, we defined a certain width and height, but there's more you can use, just check out the list below and remember that these are all optional.
px
, em
or %
. Example: data-width="300px"
data-height="600px"
data-trigger="#button"
. If you don't use this property, the modal window will be rendered as soon as it's created.
data-trigger
and must be a valid Javascript event. Example: data-trigger-event="mouseover"
.
data-responsive="false"
data-close-on-click="true"
data-disable-scroll="false"
Other options, more directed for the Javascript implementation, and a more detailed explanation of the above ones are available in the technical documentation.
"No," said Peleg, "and he hasn't been baptized right either, or it would have washed some of that devil's blue off his face."
"Do tell, now," cried Bildad, "is this Philistine a regular member of Deacon Deuteronomy's meeting? I never saw him going there, and I pass it every Lord's day."
"I don't know anything about Deacon Deuteronomy or his meeting," said I; "all I know is, that Queequeg here is a born member of the First Congregational Church. He is a deacon himself, Queequeg is."
The table component adds powerful features to a native HTML table, such as sorting and pagination, that will offer improved interactivity with tabular data.
All you need is a table and some simple data-attributes and you're set.
Before you begin, make sure you're including the necessary Javascript inside your <head>
, you'll need ink.js, ink.table.js and autoload.js.
Code
<script type="text/javascript" src="./js/ink.js"></script> <script type="text/javascript" src="./js/ink.table.js"></script> <script type="text/javascript" src="./js/autoload.js"></script>
If you opted for not using the autoload feature, then you'll need to initialize the Table component by hand. Simply include the following code, at the end of your page, before the closing <body>
<script type="text/javascript"> var t = new SAPO.Ink.Table('myTable'); </script>
To make your table columns sortable, you need to add the data-sortable
attribute to your <th>
elements. The value must be either "true" or "false" and Ink will just look a the column, figure out what kind of content it contains and then sort it, either alphabetically or numerically, depending on that content.
So, if you have a table with names and ages and you want both columns to be sortable, you simply add the data-attribute in both headers, like this:
Code
<thead> <th data-sortable="true">Name</th> <th data-sortable="true">Age</th> </thead>
Sometimes, your tables are just too long and you need to split them up by pages, without forcing your user to skip to a different page and load an entirely new table. With Ink, all you need is to specify how many rows per page you want your table to have. If your table grows to more than the specified number of rows, then it will create a new page within the table, which you can access via a pagination-style menu. Check out the Navigation section, under pagination menus to see how they work.
To have pagination, you also need to provide an empty <nav>
with an empty <ul>
element for Ink to write the page navigation into. They need the .ink-navigation
and .pagination
classes, respectivelly. Furthermore, you can configure said pagination by adding classes to the <ul>
just as detailed in the Navigation section linked above. So, you'll need this:
Code
<table data-page-size="10"> <!--tells your table to break at every 10 rows--> ... <!--your table content here--> </table> <nav class="ink-navigation"><ul class="pagination"></ul></nav> <!--pagination will be written here, automatically-->
As you can see, it's pretty easy to setup. We suggest you read our Tables section in order to create your Ink tables and then add the JS to make them work better for your users. Here's an example of a sortable and paginated table, just hit the show source code button to copy the code.
Example
Pepper | Scoville Rating |
---|---|
Trinidad Moruga Scorpion | 1500000 |
Bhut Jolokia | 1000000 |
Naga Viper | 1463700 |
Red Savina Habanero | 580000 |
Habanero | 350000 |
Scotch Bonnet | 180000 |
Malagueta | 50000 |
Tabasco | 35000 |
Serrano Chili | 27000 |
JalapeƱo | 8000 |
Poblano | 1500 |
Peperoncino | 500 |
Here's a list of the data-attributes you can use to manage your table components.
<table>
element. Example: data-page-size="20"
<th>
element. Example: data-sortable="true"
For more examples, like remote data loading via AJAX, and a list of all supported options, check our technical documentation.
The Tree View component takes a structure of nested lists and transforms it into an interactive tree with expandable and collapsible branches.
Although we recommend you use primarily unordered or ordered lists, this component can be applied to any structured group of DOM elements.
Before you begin, make sure you're including the necessary Javascript inside your <head>
, you'll need ink.js, ink.treeview.js and autoload.js if you want your module to be initialized with no hassle.
Code
<script type="text/javascript" src="./js/ink.js"></script> <script type="text/javascript" src="./js/ink.treeview.js"></script> <script type="text/javascript" src="./js/autoload.js"></script>
If you opted for not using the autoload feature, then you'll need to initialize the Modal component by hand. Simply include the following code, at the end of your page, before the closing <body>
Code
<script> var treeView = new SAPO.Ink.TreeView('.ink-tree-view'); </script>
To make a tree view, you need to create a list, with sub lists and make sure your first parent list has the .ink-tree-view
class.
To add a small state icon, indicating if a node is opened or closed, you need to add an empty <span>
in the corresponding list element. The Javascript will write the correct icon into that <span>
as required.
To make your lists expand and collapse, make sure you envelop each interactive node in and anchor element with an empty href, like so: <a href="">
.
Finally, you can indicate whether each node starts out closed, which is the default, or open, for which you need to simply add the .open
class in the corresponding <li>
.
If you check the example below, you'll see how the lists are nested, with the first branch being open by defult, then, hit the view source code button to get it. Keep reading below for more details and configurations.
Example
If by any chance you need the functionality of a tree view, with expandable and collapsible branches, but can't use a list, you can still create a functioning structure by using two data-attributes that will define which are the trigger elements and which are the interactive children.
li
, meaning you don't need this attribute if you're using a nested list. Example: data-node=".myNode"
ul
, meaning you don't need this attribute if you're using a nested list. Example: data-node=".myChild"
Note If you need to build a tree view with elements other than lists, then you will not benefit from Ink's defaul styling for this component and you'll have to add your own style.
Specifications and other examples, available in the technical documentation.
The Sortable List component allows the user to reorder items on a list, by dragging and dropping.
Before you begin, make sure you're including the necessary Javascript inside your <head>
, you'll need ink.js, ink.modal.js and autoload.js to initialize the module automatically.
Code
<script type="text/javascript" src="./js/ink.js"></script> <script type="text/javascript" src="./js/ink.sortablelist.js"></script> <script type="text/javascript" src="./js/autoload.js"></script>
If you opted for not using the autoload feature, then you'll need to initialize the Modal component by hand. Simply include the following code, at the end of your page, before the closing <body>
Code
<script> var sortableList = new SAPO.Ink.SortableList('#slist'); </script>
Making a sortable list is as easy as using a class. Build a <ul>
with the .ink-sortable-list
class, and you're set. By default, your <li>
elements can be dragged and their order changed by the user.
If you need your sortable list to work differently, check the configurable attributes after the example. Click the view source code button to get a functional snippet.
Example
<li>
, can be set to any CSS selector. Example: data-drag-object=".myClass"
.If you check the example code above, you'll see we created a "drag here" label and made that the draggable element with data-drag-object=".ink-label"
Check our technical documentation for further configuration.
The date picker component adds a flyout calendar to a textbox, within a form, so your users can just click the box and pick a date, visually, instead of having to guess the date format or you having to print specific instructions to explain that format.
Using the date picker also guarantees that you get your dates in the format you need, without extra form validation.
Before you begin, make sure you're including the necessary Javascript inside your <head>
, you'll need ink.js, ink.datepicker.js and autoload.js.
Code
<script type="text/javascript" src="./js/ink.js"></script> <script type="text/javascript" src="./js/ink.datepicker.js"></script> <script type="text/javascript" src="./js/autoload.js"></script>
If you opted for not using the autoload feature, then you'll need to initialize the component by hand. Simply include the following code, at the end of your page, before the closing <body>
<script type="text/javascript"> var picker = new SAPO.Ink.DatePicker('#myDatePicker'); </script>
Creating a date picker couldn't be easier. All you need is a text input in your form, tagged with the .ink-datepicker
class. And that is all.
Like other Ink Javascript components, the date picker is configurable by using data-attributes, which we will detail below. For now, let's see what your code should look like. Remember, you are within a form, so go read up on Ink forms, if you need to.
Code
<input type="text" id="date" class="ink-datepicker">
That is the basic of basics for getting a date picker, but there is a more complete example below, grab the code by hitting the view code button. Then, you can read up on all the ways you can configure your date picker, using data-attributes.
<div class="control-group"> <label for="dPicker">A date field:</label> <div class="control"> <input id="dPicker" class="ink-datepicker" type="text"></input> </div> </div>
The calendar has some really useful features you might want to be aware of. On the top left corner you have a link to clear the input box, in case you've entered a wrong date, and on the top right, you can click to close the calendar.
On the next line, you have navigation chevrons on either side, that will allow you to navigate by month and in the center, you can click either the month name to directly pick another month, or the year, to pick a different year, without having to navigate by hand to those dates. When you click a day, the date gets written into the input field. Just click the above example and try it out.
To further configure your date picker, just add data-attributes to your text input field. Here's a comprehensive list of all the attributes you can use on the date picker.
data-format sets the date format which will be written into the text input and submitted with the form. The default value is data-format="yyyy-mm-dd"
but there are many different options as you can see below:
data-position specifies where the calendar will appear, relative to the input field. Example: data-position="bottom"
. Possible values are:
data-css-class sets a class for the calendar. The default value is data-css-class="sapo_component_datepicker"
, but you can change it to any class you need to use in your project to style the calendar.
data-start-date sets a start date, that will be selected when you open the calendar. It must be defined in the following format: yyyy-mm-dd
. Example: data-start-date="2013-01-01"
There are other configurations, some specific for Javascript, available on the technical documentation.
The Tabs Component offers a simple way to build a tab-separated layout, allowing you to offer multiple content in the same space with intuitive navigation.
Before you begin, make sure you're including the necessary Javascript inside your <head>
, you'll need ink.js, ink.tabs.js and autoload.js to initialize the module automatically.
Code
<script type="text/javascript" src="./js/ink.js"></script> <script type="text/javascript" src="./js/ink.modal.js"></script> <script type="text/javascript" src="./js/autoload.js"></script>
If you opted for not using the autoload feature, then you'll need to initialize the Tabs component by hand. Simply include the following code, at the end of your page, before the closing <body>
Notice that, in this particular case, when initializing the module, you'll have to declare which tab is active on load and which aren't, by using their respective indexes.
Code
<script type="text/javascript"> var tabs = new SAPO.Ink.Tabs('.ink-tabs', { disabled: ['#stuff', '#more_stuff'], active: '#news', onBeforeChange: function(tab){ console.log('beforeChange', tab); }, onChange: function(tab){ console.log('Changed', tab); } }); </script>
To make a tabbed view, you'll need a block element with the .ink-tabs
class, such as a <div>
, within which you'll have a <ul>
for your tabbed navigation and a set of <div>
elements to hold the content of each tab. Your .ink-tabs
element should also have a class to determine where the navigation will be in relation to the content: .top
, .bottom
, .left
or .right
The <ul>
must have the .tabs-nav
class and each list element must be wrapped in an anchor pointing to a valid ID in the content of the tabs.
Each of the <div>
holding the content, must have the .tabs-content
class and an ID that matches the navigation anchors.
If you're making a tabbed view with tabs on top, on the left or on the right, put the navigation first in your markup, if you need the tabs at the bottom, then, put the content first and the navigation after.
Examples of each and a full code snippet will follow, but for now, let's look at an example code, just to clarify everything.
Example Code
<div class="ink-tabs top"> <!-- Creates a tabbed view with top nav --> <ul class="tabs-nav"> <li><a href="#item1">Item 1</a></li> <!-- Points to item 1 below --> <li><a href="#item2">Item 2</a></li> <!-- Points to item 2 below --> ... </ul> <div id="item1" class="tabs-content"> <!-- Item 1 --> ... <!-- Your tab content here --> </div> <div id="item2" class="tabs-content"> <!-- Item 2 --> ... <!-- Your tab content here --> </div> ... </div>
Example With top navigation
Example With bottom navigation
Example With left navigation
Example With right navigation
As with most Ink JS components, you can add extra features to the tabs via data attributes. Check the following list for attributes you can add to your .ink-tabs
<div>
data-prevent-url-change="false"
data-active="#secondItem"
You can see several examples in the technical documentation.
The Form Validator component provides an easy way to validate forms before submitting them. It can:
Before you begin, make sure you're including the necessary Javascript inside your <head>
, you'll need ink.js and ink.formvalidator.js.
Code
<script type="text/javascript" src="./js/ink.js"></script> <script type="text/javascript" src="./js/ink.formvalidator.js"></script>
Notice that, contrary to other modules, you don't really need to initialize the Form Validator, as the validation request is made on form submission.
There are two components that you need to use in order to validate a form using Ink. You'll have to request validation on form submission and you'll have to tag the input elements with certain classes to tell Ink what to validate.
So, start by building your form (make sure you read the sction on forms), and add the bit of Javascript that tells Ink to do the validation in your <form>
, like this:
<form class="ink-form" method="post" action="#" onsubmit="return SAPO.Ink.FormValidator.validate(this);">
Once you have the onsubmit
attribute set, you need to 'tag' each of your input elements (text, radio buttons, select boxes, etc), with one or more validation classes. Refer to the following list to see what they do:
More examples and detailed configurations, in the technical documentation.
The Progress Bar component gives the .ink-progress-bar markup it's animated behavior.
It also allows the user to set the progress in runtime.
This component has the following configurable data-attributes:
The Image Query component allows you to load different image sources, depending on the viewport width. It has the following features:
More specifications and other examples, available in the technical documentation.
Sticky keeps an element "stuck" as you scroll the rest of the page. The best example is the side menu on this website. To use it, add the .sticky
class to a block-level element in your layout.
Check the technical documentation for more details.
Collapsible turns your horizontal menus into vertical ones depending on the screen width. It gives you the possibility to collapse/expand your menus.
Activate it by using the ink-collapsible
class. A working example of collapsible is the top most menu.
Check the technical documentation for more details.
When clicking an element with the ink-close
class, the first ink-alert
or ink-alert-block
ancestor is removed from the document.
Activate it by using the ink-close
class inside of an element with one of the previously mentioned classes.
Check the technical documentation for more details.