Permit.js

Use Cases:

• Authentication: Logged-Out / Logged-In
• Membership: Free / Paid
• Connectivity: Online / Offline

• Roles: Writer / Editor / Publisher
• Permissions: User / Moderator / Administrator
• Content: English / French / Spanish

How Does it Work

It's pretty simple. The plugin combines javascript-generated cookies with a set of dynamically-generated CSS utility classes to show and hide content. When you "issue a permit" with permit.js you're really just creating a cookie that remains in the browser throughout your prototype. Content is then displayed or hidden based on the existence (or non-existence) of the permits that have been issued.

That's all? Did it really need a plugin?

Permit.js greatly simplifies the process of managing cookies and using them to create dynamic, multi-state prototypes. Cookies can be created, updated/swapped, and destroyed solely through your CSS classes (e.g., class="permit-issue-mystate"). Furhter, it provides a highly flexible, universal, and project-specific (semantic) means of doing all of this.

Sure, you could write your own js and css to do the same, but you'll probably find yourself re-writing and altering the code for your next project. Trust me, that's what I found myself doing, and that's why I made it. In addition, if you're not comfortable with javascript, you barely have to touch it.

Usage

1 Include dependencies and permit.js

Permit.js requires jQuery and the jquery.cookie plugin. You must load those before you load permit.js.

<script src="js/jquery-1.10.1.min.js"></script>
<script src="js/jquery.cookie.js"></script>
<script src="js/permit.min.js"></script>

2 Instantiate

The only required setting is the 'permits' setting. This is where you specify your states.

$(document).ready(function(){
    $.permit({
        permits: ['free','premium','admin']
    });
});

Currently, the plugin has one additional optional setting.

3 Create a "Permits Agent"

The optional "agent" will help you issue your permits and change between your states. Create a container with an ID of 'permit-agent'. When the script is instantiated, this container will be populated with a dropdown of your available permits. The agent issues a new permit when you click on an element with a class of 'permit-reissue'. You don't have to use the agent. If you prefer you can just issue or revoke permits using the plugin's helper classes.

<div>
    <div id="permit-agent">
        <!-- A dropdown with your states. -->
    </div>
    <button class="permit-reissue">Issue Permit</button>
</div>

The demo includes the agent inside a Twitter Bootstrap modal. This is purely for effect. You may place your agent anywhere.

4 Apply CSS

Permit.js creates several personalized helper classes based on your instantiation settings. All you need to do is apply a generic 'permit' class plus one of these personalized classes to your HTML markup. The following example shows how you might apply your CSS classes in the case of three states: free, premium, admin.

Custom Classes

<div class="permit permit-free">
    <p>Visible to free users (only).</p>
</div>

<div class="permit permit-premium">
    <p>Visible to premium users (only).</p>
</div>

<div class="permit permit-admin">
    <p>Visible to admin users (only).</p>
</div>

Combining Classes

You can combine any of your custom classes. For example, if you want a block to show for free and premium users, but not admins, you could do the following:

<div class="permit permit-free permit-premium">
    <p>Visible to free and premium users, but not admins.</p>
</div>

Default Classes

In addition, you can use .permit-all and .permit-none classes.

<div class="permit permit-none">
    <p>Visible only when no permits have been issued (e.g, in a fully logged-out state).</p>
</div>

<div class="permit permit-all">
    <p>Visible to all permit levels. Invisible if no permits are present.</p>
</div>

Additional Helper Classes and Advanced Usage

Permit.js provides additional helper classes that allow you to create even more complex, interactive experiences. Also see the plugin's API for even greater flexibility.

<div class="permit permit-force permit-premium" data-permit-message="Please <a href='#'>upgrade</a>">
    <p>This content will show when a premium permit is present, otherwise it shows the message defined in the data-permit-message attribute.</p>
</div>

Public API Methods

For the ultimate control on issuing (or revoking) a permit, try the API. You can issue (or revoke) a permit whenever, wherever, and however you want.

Settings & Options