Getting Started
  1. Introduction
  2. Support Information
  3. Standard Installation
  4. WordPress Installation
  5. Installation Recap
Components
  1. ASCII Boxes
  2. Images and Videos
  3. Cursors and Text
  4. Bootstrap Skin
Changelog
  1. Changelog

Shell v1.2.3

ASCII / Code Page 437 Framework


Thank you for purchasing Shell. You don't need to know jQuery to use Shell - just basic HTML. Some experience with Bootstrap for the Bootstrap Skin is expected. The documentation will guide you from start to finish. You are probably excited and ready to begin, but relax - it may be confusing if you don't read the complete documentation.

I've done my best to write this documentation at a beginner level, taking into consideration that English may not be your first language. For this reason, parts of the documentation may seem repetitive. Licensing Please make sure you have purchased the appropriate License for Shell. Licenses are single-use and allow you to use Shell with 1 client or 1 website. Each additional website you plan to use Shell with requires its own license. An Extended License if required when you are:

Piracy You should be aware that this software is the intellectual property of Crusader12. Shell is sold on multiple markets under the Crusader12 profile. If you encounter this item under another profile please notify me so that I may take action.

A third-party company has been hired to protect Crusader12 plugins on a long-term basis, and properly address any criminal activity. Usage of this item may be monitored and logged for these purposes alone.

"Software theft is a serious matter. If you or your company get caught copying software, you may be held liable under both civil and criminal law. If the copyright owner brings a civil action against you, the owner can seek to stop you from using its software immediately and can also request monetary damages. The copyright owner may then choose between actual damages, which include the amount it has lost because of your infringement as well as any profits attributable to the infringement, or statutory damages, which can be as much as $150,000 for each program copied."
- BSA - The Software Alliance
The Digital Millenium Copyright Act of 1998

More Crusader12 Plugins

Read this documentation in it's entirety before using Shell - and have fun!

Support Information

I stand behind my products and will provide as timely support as possible.
I do reserve the right to withhold support for the following reasons:

Where to Look First Before requesting support, please make sure that you have read the Documentation entirely. I have worked very hard to make sure this documentation covers everything clearly, and will update portions of it that are reported as confusing. I have also included a Troubleshooting Section at the end. The Frequently Asked Questions section (now located under the Support Tab on the Shell Item Page) will also be updated often. Updates Shell is setup to be modular and heavily expanded. I'm excited at the thought of updating this item, but I need to know if people are enjoying it. It only takes a second to rate Shell and leave feedback in the Comments Section. I have a passion for classic Adventure Games. Feedback (not sales) will decide how quickly Shell is expanded.

Please take a moment to rate and share it with your friends. Ratings are very important, and will determine how quickly the plugin is updated and how much time I am able to devote to it.

Please take a few seconds to rate Shell by logging in to your account. If you have any feature requests or ideas, I would be happy to hear them.

Standard Installation

This section is for standard HTML websites. For WordPress/CMS installations, see WordPress Installation. Shell has a few required files. Installation is only a matter of uploading the following files to your server and linking them on your page.

Step 1: Upload the Shell Folder to your site's root folder. This is typically where your index.html file resides.

Step 2: Link the Shell CSS file in the <HEAD> section after your stylesheet. You can copy the following: <link rel="stylesheet" href="Shell/css/jquery-shell-1.2.css" type="text/css" media="all" /> It's recommended to place this after your other CSS Links, to avoid overwriting Shell styles.

Step 3: If your website does not have jQuery installed, link the jQuery file in the <HEAD> section of your page.
<script type="text/javascript" src="Shell/js/jquery-1.11.1.min.js"></script> To check if jQuery is already intalled on your site, look in the <HEAD> section of your page for a <SCRIPT> tag with 'jquery-x.x.x.xxx.js' in the src attribute (Where x would indicate a version number). jQuery is a JavaScript library that provides a set of tools which Shell uses. Since parts of Shell rely on these components, it's important that jQuery is loaded before the Shell Javascript file. It's optimal to place jQuery before all other <SCRIPT> links.

Step 4: Link the Shell JavaScript Plugin File. <script type="text/javascript" src="Shell/js/jquery-shell-1.2.min.js"></script> Shell should be loaded after jQuery.

Step 5: Last, confirm that all files have been correctly linked. Open Firefox (Firefox is recommended for this step). Navigate to your website. View the source code by pressing CTRL-U (CMD-U on Mac). A window will open revealing the source code. At the top - inside the <HEAD> section of the page, you'll see all of the links you've added. When linked correctly, clicking the link should navigate to the file contents. If the file contents don't appear, the browser can't find the file at the path you specified.

Complete Code: Below is the correct loading order. You can also refer to the included demos for more examples.

<HEAD>
...
<link rel="stylesheet" href="Shell/css/shell-1.2.css" type="text/css" media="all" />
<script type="text/javascript" src="Shell/js/jquery-1.11.1.min.js"></script>
<script type="text/javascript" src="Shell/js/jquery-shell-1.2.min.js"></script>
...
</HEAD>


WordPress Installation

This section is for WordPress websites. Installation has been broken down into small, detailed steps. Installation involves uploading these files to your server and linking to them on your page.

Step 1: Upload the Shell Folder to your WordPress Theme Folder.

Step 2: Login to the back-end of WordPress and navigate to Appearance -> Editor. Click the header.php in the right sidebar to open your header file which contains the <HEAD> section. Locate the <LINK> tag to your main style.css file and insert the following directly after. <link rel="stylesheet" href="<?php bloginfo('template_directory'); ?>/Shell/css/shell-1.2.css" type="text/css" media="all" /> It's recommended to place this after your other CSS Links, to avoid overwriting Shell styles.

Step 3: WordPress comes with jQuery installed, however you should check to see if it's enabled. Navigate to your website front-end and view the source code (CTRL-U / CMD-U on Mac). Run a search for "jquery". If you find a SCRIPT tag linking to jQuery then you don't need to include the jQuery file that came with Shell. Most of the time jQuery will be enabled and you're probably already using other jQuery plugins in your theme. However, in the rare case it is disabled, please email me directly for instructions.
Some Themes may choose to link JavaScript files in the footer.php

Step 4: Link the Shell JavaScript Plugin File at the end of the <HEAD> section. <script type="text/javascript" src="<?php bloginfo('template_directory'); ?>/Shell/js/jquery-shell-1.2.min.js"></script>

Step 5:Last, confirm that all files have been correctly linked. Open Firefox (Firefox is recommended for this step). Navigate to your website. View the source code by pressing CTRL-U (CMD-U on Mac). A window will open revealing the source code. At the top - inside the <HEAD> section of the page, you'll see all of the links you've added. When linked correctly, clicking the link should navigate to the file contents. If the file contents don't appear, the browser can't find the file at the path you specified.

Complete Code: Below is the correct loading order for the required files. You can also refer to the included demos.

<HEAD>
...
<link rel="stylesheet" href="<?php bloginfo('template_directory'); ?>/Shell/css/shell-1.2.css" type="text/css" media="all" />
<script type="text/javascript" src="<?php bloginfo('template_directory'); ?>/Shell/js/jquery-1.11.1.min.js"></script>
<script type="text/javascript" src="<?php bloginfo('template_directory'); ?>/Shell/js/jquery-shell-1.2.min.js"></script>
...
<HEAD>



The <?php bloginfo('template_directory'); ?> points to the root directory of the active Theme. You can alternatively use absolute paths, but this is the recommended method.

Installation Recap

Shell installs like any other jQuery plugin. Just upload the Shell folder to the root folder of your website (or your WordPress Theme Folder). Make sure that your website has jQuery installed - if it doesn't, load the version included with Shell. Make sure that the loading order is correct as detailed in the Installation section.

Shell is now installed and ready for use.

Containers

Before we dive into making different effects, it helps to understand what Shell is doing. Shell is based around the simple idea that nearly every website animation effect can be achieved with 2-3 simple HTML containers. This approach can actually be more efficient and lightweight than writing custom code specific to each effect. When you call Shell on an element, it builds those animation containers around that element. To the right is a diagram of what elements are made and how they interact with each other. Understanding this diagram will help when setting up your effects.

Container Your element is wrapped inside of the Shell Container (outlined in black). Background The Background element (shown in gray) is placed inside of the Shell Container. This example shows the Background positioned like a Caption. The position of the Background Container is relative to the Container and a Coordinate System is used to position the Background. Basically, 0,0 will position the Background at the top-left corner of the Container.
Later you will learn that the "coords" setting controls the movement of this container. Text Container The Text Container (shown in Blue) is positioned inside of the Background Container and can also be animated independently.
Later you will learn that the "text_coords" setting controls the movement of this container. Effects use a different combination of the above containers

ASCII Boxes

ASCII Boxes allow you to get a full, accurate styling using only pure CSS and Code Page 437 Characters. If you're unfamiliar with the box drawing characters of yesteryear - you can check them out here. Setting up an ASCII Box In order to achieve a true ASCII Box look, several DIVs are required - but Shell handles this for you. You can refer to the ASCII Box examples included in the download as well. The basic structure of an ASCII box: <div class="Shell-box" data-ascii='{ }'>
<h1>ASCII BOX</h1>
<div class="Shell-box-content">
<p>Box content...</p>
</div>
</div> Notice it is simply a main Container (with class="Shell-box"). This container tells Shell that this is the ASCII Box, and all contents should be styled like one. Next, the H1 tag is used as the TITLE of the ASCII Box and the inner DIV (class="Shell-box-content") is the Scrollable Container. All of your HTML content is placed inside the Scrollable Container.

There are a few things to note about styling. All of the CSS has been separated into logical sections - with the dimensions at the top. This is done if you want to make your ASCII Boxes responsive. When doing so it is highly recommended to use Firebug, or a similar tool to inspect elements and see how everything works.

To size your ASCII Box, add a new special class to it. In this case, we'll add "Shell-box-1". Then create the CSS class inside the Core Shell CSS file (where it says insert your custom dimensions here). <div class="Shell-box Shell-box-1" data-ascii='{ }'>
<h1>ASCII BOX</h1>
<div class="Shell-box-content">
<p>Box content...</p>
</div>
</div> Settings You'll notice that the main DIV has a data-ascii='{ }' attribute. This is used to pass in options to this specific ASCII Box. Below are some available settings: To position the ASCII Box (X,Y percentages): "coords" : "0,0" To change the Code Page 437 Box Drawing Character for the Shadow you can use a pre-defined character by selecting a number from 1-9. You can also use 0 for none. "shadow_type" : 5 You can enter a specific code from the Code Page 437 list. "shadow_type" : "code:2022" ASCII Boxes are optionally draggable. You can control this using: "draggable" : true When Dragging is enabled for an ASCII Box, you can define the Drag Handle by suppying the unique ID of the element within the ASCII Box. For example, if you want the user to only be able to drag the ASCII Box around by the title, then you would assign a unique ID to the H1 tag (id="drag_me") for example, then use: "drag_handle" : "drag_me" By default, ASCII Boxes are pulled to the front when they receive focus. If you have other elements that are working with the zIndex or need to disable this you can change this setting: "stay_on_top" : "1,2" By default, each ASCII Box has a Close Button and a Minimize Button. You can disable these by using: "buttons" : "false,false" You can control the Code Page 437 Characters of the Close Button using: "close_button" : "code:25A0" You can control the Code Page 437 Characters of the Minimize Button using: "min_button" : "code:2193" You can control the Code Page 437 Characters of the Maximize Button using: "max_button" : "code:2191" You can control how the ASCII Box scrolls up and down - allowing for jerky scrolls if desired: "scroll_height" : "100px"

ASCII Images and Video

You can easily convert images and videos to ASCII artwork using Shell. ASCII Images To convert an image to ASCII artwork, just use: class="ascii-img" ASCII Videos To convert a video to realtime ASCII artwork, setup your HTML5 video as usual: <video width="1024px" height="574px" preload controls>
<source src="vid.mp4" type="video/mp4">
<p>Your browser doesn't support HTML5 video.</p>
</video>
Then simply add class="ascii-video" and any options using the data-ascii='{ }' attribute.
<video class="ascii-video" width="1024px" height="574px" preload controls data-ascii='{
"fps":40,
"letters":"XMI/-.",
"invert":true,
"controls":"#vid_controls"}'>
<source src="vid.mp4" type="video/mp4">
<p>Your browser doesn't support HTML5 video.</p>
</video>
Video Options Above, we're passing in some options to the VIDEO tag. The class="ascii-video" tells Shell that you want this video to be converted to ASCII in realtime. The data-ascii='{ }' attribute passes in settings to configure how you want this specific video set up. Below are Shell video settings:

The frames per second (FPS) setting, allows you to tell Shell how many frames per second the video should be playing at. Adjusting this may get better ASCII results. "fps" : 40 To fine-tune how your ASCII video looks, you can choose your own characters (as many as you like), from dark to light, using: "letters" : "aBCDE" To invert the video, use: "invert" : true You can also assign a unique DIV that contains controls to this video, using: "controls" : "#vid_controls" In this example, the controls DIV would look like: <div id="vid_controls">
<div class="ascii-play">Play</div>
<div class="ascii-mute">Mute</div>
</div> You can style the Play and Mute buttons however you like, and assign each by simply adding the appropriate classes. Note: Video Playback will not happen locally and must be tested on a server.

Cursors and Text

Blinking Cursors To setup a Blinking Cursor, use: <span class="ascii-blink">|</span> You can configure the speed inside the core Shell CSS file (search for .ascii-blink) Typed Text Shell provides an option for mimicing typing text. This works on any HTML element, but specifically heading tags and paragraph tags. For example: <h3 class="ascii-type" data-ascii='{
"text" : ["Text 1", "Text 2", "Text 3"]
}'></h3> Above, we have declared this element to use animated typing by adding class="ascii-type". It is then configured using the data-ascii='{ }' attribute. Animated Type has a few options: "text" : ["Text 1", "Text 2", "Text 3"] The text will first type out "Text 1", then delete it, type out "Text 2", then delete it, then finally type out "Text 3". You can add as many strings as you like, comma separated. Control the typing speed: "type_speed" : 500 Control the typing delay: "type_delay" : 500 Control the deleting speed: "back_speed" : 500 Control the deleting delay: "back_delay" : 500 Set whether the animation loops: "type_loop" : true If looping, control the number of times to loop - or use 0 for infinite: "loop_count" : 0 Show or Hide the cursor: "show_cursor" : true Use a different character for the cursor: "cursor_char" : "|" Callback when done typing: "type_callback" : function Callback before each string: "pre_text_callback" : function Callback for every typed string: "on_string_type" : function Callback for reset: "on_reset" : function

Bootstrap

Shell includes a complete Bootstrap 3.2 Skin.

The main BootStrip demo page is included in the download and titled bootstrap-shell.html. You can use this as a guide for what HTML and CSS to use to accomplish specific components.

The actual Skin file is located in Shell/bootstrap/css/bootstrap-shell.css

Changelog