viewSwitcher is a dependency free, isolated module to handle different "views" and very basic
"routing" through URL hashes. ViewSwitcher exposes the global Variable View
that holds
all its functionallity.
You can see the Feature List for more details.
This script is under more or less active development and as development moves, there may be breaking changes. As I try to go with semver you'll see at the version number if this is a breaking release nor not.
This project is open source at GitHub, feel free to request features, send pull request or report issues.
Feature List
Plug 'n Play
Load the module, add a navigation wrapper (if wanted), set a default view and start adding your views - that's it.
Each view is represented by a Block Element (div
, article
,
section
, etc.) and add a data-view
Attribute to it. This Attribute
determines what hash this View is loaded by.
// loaded by myurl.com/#home
<div data-view="home"></div>
Commented code
I tried to comment the code but I suck at it. Everytime I'm working on viewSwitcher I try adding more detailed comments. Extend/rewrite as you wish!
URL Handling
ViewSwitcher automatically handles "URLs", so yourdomain.com/#viewname will load the associated view. This noobish routing is the most basic handling I could think of.
Title handling
The page title is automatically replaced based on the current view. Currently, this cannot be
turned off. The title is always composed from VIEW_NAME — ORIGINAL_TITLE
Documentation
A quick feature overview.
Markup
To use ViewSwitcher simply include the libary and start writing your single-page site. Every view can be represented as a section as seen below
<section data-view="myview">
This is my view, my url will be your.tld/#myview
</section>
As you can see the data-view
attribute is turned into the URL.
Generating Menus
To generate a menu you can specify a navigation wrapper and use the View.getHtmlMenu()
function. The function accepts a string which is used as
class name for every nav item and returns a ul containing li's as navigation.
var menu = document.querySelector('nav');
menu.innerHtml = View.getHtmlMenu('nav__item');
Assigning Menus
With View.setMenu(node)
you can assign an existing HTML Menu to viewSwitcher. This menu is then used in the setupEvents function. This menu can either be hand-made or autogenerated by the getHtmlMenu() function. As of v0.0.5, it is required that you assign a menu if you don't use custom JavaScript to handle your VIEW menu.
If you don't generate the Menu with getHtmlMenu
and just want to reference it, you can also pass in a String like #nav
as argument. setMenu
will then run document.querySelector
against your string to match the Node representing the Menu.
// Create an menu and tell viewSwitcher to use the nav element as Menu Wrapper/reference
var nav = document.querySelector('#nav');
nav.innerHTML = View.getHtmlMenu('nav__item');
// Here we tell viewSwitcher to use the `nav` element as
// menu item.
View.setMenu(nav);
// Example 2
// Only assign the menu, which is a self-made Menu with an ID of myMenu
View.setMenu('myMenu');
Excluding Views
To exclude a view, simply add a data-view-exclude="true"
attribute to the view
container. It actually doesn't even need a string passed, viewSwitcher only checks if
data-view-exclude
is set - the value doesn't matter.
<section data-view="myview" data-view-exclude="true">
This view won't appear inside the generated menu.
</section>
Disabling Options
With version 0.0.4 the new setOptions
function was introduced. Pass in an object of
to configure viewSwitcher as you need!
- Supported Options
- changeTitle - shoudl the Page Title be manipulated? TRUE or FALSE
- setupEvents - should viewSwitcher setup common click handlers for you? - TRUE or FALSE
By default both options are set to true.
View.setOptions({
changeTitle: true,
setupEvents: true
});
In-page view
As of version 0.0.5 you can just "normally" link to any view inside your page. Create an
a
tag and assign a link like /#mypage
to it. If setupEvents
is not disabled via the setOptions
function, viewSwitcher will handle clicks on
any links and decide if it is an internal or external link.
Note: This is experimental and may break. Please report all issues on GitHub.
<a href="/#about"></a>
Init Active
There's a initActive
function to automatically set a view as active if no hash is given.
View.initActive('home');
Changelog
- v0.0.5
- New
initEvents
function that will assign default Events (see Documentation). It can be turned off withView.setOptions({setupEvents: false});
- New in-page handling! If a link has no URL but a Hash (#), viewSwitcher will try and activate a View.
- v0.0.4
- Added new function
setOptions()
. Pass an object to configure viewSwitcher. Currently supported:changeTitle
, this can be true or false - added documentation for setOptions
- added new example: CV
- v0.0.3
- fixed
window and document
not being passed to the IIFE. - added
data-view-exclude
Attribute - added documentation for in-page viewSwitcher links and how they're handled at the moment.
- kept on commenting and documenting
- v0.0.2
- added better URL handling
- added init function to set variables
- initial cross-browser testing
- v0.0.1
- Initial release