Theme: Normal

Pines Steps

JavaScript steps (wizard) for Bootstrap.

Download Pines Steps X.X Pines Steps on GitHub GitHub Icon

Using Pines Steps Issue Tracker Bug Report/Feature Request

About

Pines Steps is a JavaScript steps (wizard) plugin, developed by Angela Murrell as part of Pines. It is designed to provide an unparalleled level of flexibility, while still being very easy to implement and use.


Pines Steps is useful for step-based transitions. We encourage the use of custom validation to show progression to users, so that the experience of completing linear tasks on the web is easier and user-friendly!

Not just a Wizard

Pines Steps is not just any wizard. Pines steps indicates the progress of each step and is easily configured to just about any project. Whether it's for a website sign-up form or a survey or test, you can use Pines Steps and start rendering the experience of linear movement on the web with progress indication!

Cross-Browser

Pines Steps works in all major browsers and provides a consistent interface. It is tested thoroughly for consistency.

Semantic

There are no specific elements you must use for Pines Steps. This allows you to use the most semantically correct elements (even HTML5 elements) in your design.

Completely Open

Pines Steps is distributed under the GPL, LGPL, and MPL. This triple copyleft licensing model avoids incompatibility with other open source licenses.

Demos

Before Steps

This is an example before psteps is called on the parent of our intended steps. This example has all the appropriate classes necessary for 5 steps, and the titles and contents are according to source order. We've given step-contents that aren't supposed to show up initially a class of hide, which is a bootstrap class to keep them from appearing before psteps styles them.

Simple Steps

This is the default psteps. In this example, you can never click the step titles. Remember that scaffolding the layout is all up to you. Here we designed a vertical sidebar for step titles.

1. Step 1
2. Step 2
3. Step 3
4. Step 4
5. Step 5
Step 1
Step 2
Step 3
Step 4
Step 5

Add Validation

In this example, you can only click the step titles if you have visited the step. We added a click event (on the boxes) that triggers our validation rule. Our rule only indicates success (green title) when the right box is clicked. It will remain incomplete (blue title) if wrong. This example also shows that you can use any order naming for your titles (a-c).

a. Pick a Yellow box
b. Pick an Orange box
c. Pick a Purple box

Choose the yellow box:

Choose the orange box:

Choose the purple box:

Strict - Indicates Incorrect Answers

In this example, you may not advance to the next step if there are errors or if it is incomplete. You may not back track. Titles are never traversable. Because we utilized errors in our validation rule, we have an immediate indication of wrong answers, unlike the example above. This example does not show the step orders, except at small viewports, when the step titles shrink to only show the step order. These are all options.

i. Pick a Yellow box
ii. Pick an Orange box
iii. Pick a Purple box

Choose the yellow box:

Choose the orange box:

Choose the purple box:

Conditional Validation

So far we've seen steps that validate if all steps use the same validation rule. This example shows how to construct different validation rules. Notice that the titles are always traversable (and as a result they always indicate progress). This example also shows the difference between an error and a warning, where warnings will still allow progression and errors will not.

1. First Name
2. Middle Name
3. Last Name

Simple Horizontal layout

In case you were curious, here's a sample of the simple steps in a horizontal layout. We only used a few options to help control the responsive presentation of the steps in a horizontal layout.

The plugin does not interfere with your styling or layout flexibility. You only need to make sure that step-title and step-content classes correspond according to source order.

1. Step 1
2. Step 2
3. Step 3
4. Step 4
5. Step 5
Step 1
Step 2
Step 3
Step 4
Step 5

Practical Use

This example shows a more practical use for the plugin, and also shows how helpful multiple validation rules and progress indication can be. The addition of the colored asterisks shows how easy it is to make validation rules more robust. Also, this example utilizes the content headings option which displays the name of the step in the content as a heading. Keep in mind that the validation rules for this example are much more complicated, because we are using different validation rules not only between the steps, but within the steps too.

1. Sign Up
2. Basic Info
3. Account Settings
4. Security Settings
Make Profile

Design your Psteps

This example shows that you can design your psteps however you want them to look. You can be creative with your design and you can use some options from the plugin to adjust/equalize the width and height of the titles and/or content areas. Psteps does very little to style itself, other than the bootstrap classes to indicate colored progress on the titles and transition buttons (next, submit, back). This example also shows the use of step orders, without ever displaying step-names or check marks. It's important to still set the step names, though, because they are used for the content headings.

1Register
2File Claim
3Product Info
4Sale Info
5Troubleshoot Description
Registering is easy!
Content 1...
After filing your claim, you'll hear from us shortly.
Content 2...
We can process your claim quicker if you provide product information now.
Content 3...
Content 4... There is no before heading section on this step.
Provide a description of the things you've already done to troubleshoot your problem.
Content 5...

Practical use for Circles Titles

This example also shows another application of the plugin - a test. Psteps is extremely useful for many different environments where linear steps are needed, whether through website registration or educational lessons/tests. The advantage of Psteps is that it has progression indication and is extremely versatile because its validation rules can be tailored to each unique, specific project.

Notice that this example shows the user that the answer is wrong after advancing to the next step. This differs from our Strict Example from earlier because the Strict Example immediately relayed to the user that they were wrong and would not allow progression until corrected. In this test example, we do not want the user to be able to change their answer, but we do want to indicated to the user the success of their answer.

The titles are not initially traversable during the test. You'll notice, if you complete the test, that we utilized the load_after_steps function and trigger upon clicking the submit button. The function we wrote in load_after_steps creates a review button and shows the results of the test. Clicking the review button triggers the event traverse_always so that all the titles can be clicked now. Also triggered by the review button is the event go_to_first_error, if there are any, which takes the user to the first question they answered incorrectly.


12+3 = ?
211-6 = ?
37 x 8 = ?
4144 / 12 = ?
5(2+3) x (11-6) = ?
6(7-8) x (10) = ?
7(15+30) / (9-6) = ?
86(2+3) = ?
922 - 9 x 2 = ?
1017 x 2 + 1 = ?
1117 x (2+1) = ?

Test Results

You correctly answered out of questions.

That's %!

Options

Below is a table that shows the options and brief descriptions about them.

Name type default description
traverse_titles string 'never' How step titles can be traversed - never | always | visited. Keep in mind that validation is not applied to the titles being traversed. This may trigger your reasons for using 'never' or 'visited'. You can also trigger the event traverse_always | traverse_never | traverse_visited to switch up traversal after psteps has been initialized.
content_headings boolean false If step names should be copied to step content and used as headings.
content_headings_element string 'h4' The element inside the content headings div to wrap around the step name. For example, 'h4'.
content_headings_hr boolean true If the content headings have an <hr/> after them.
content_headings_after mixed false Use a string to provide a selector for which the heading will be placed after. If nothing matches the selector within a step, it will use the default and prepend the step (show at the beginning). If false, the option is not used.
step_order boolean true If the step-order contents are displayed all the time. These are always shown if shrink_step_names is true. Step orders are usually numbers (1. 2. 3. etc)
step_names boolean true If step names are shown. Even if you don't use step names, you should define them in your html so they can be used for content_headings.
check_marks boolean true An option for checkmarks/error icons when things are completed/errored/warned. Checkmarks are not always good for every design, like the circle step design.
alter_width_at_viewport string '1000' At specified screen size, steps_width_percentage will execute.
steps_width_percentage boolean false Make width of step titles an even percentage for the number of steps. Useful for certain designs and responsiveness. Triggered on load and when screen resizes.
steps_height_equalize boolean false Make all step title heights equal to the biggest height. Triggered on load and when screen resizes.
content_height_equalize boolean false Make all step content heights equal to the biggest height. Triggered on load and when screen resizes.
alter_names_at_viewport string '650' At specified screen size, shrink_step_names will execute.
shrink_step_names boolean true Do not display step names in small viewports, just numbers. Extremely useful! You specify the viewport to do this at.
back boolean true If there is a back button.
use_custom_back_button boolean false Specifies whether to utilize a custom back function callback on the click event.
custom_back_button_click function undefined, num Function arguments are undefined, num, where num is the integer representing the previous step to go back to. Useful if you want to reload the whole page instead of just showing the previous step. You could only refresh the page if certain steps were completed, or loaded in a completed state.
step_start string '1' Set the default step to load.
start_incomplete_step boolean false Go to the first incomplete step. Setting to true overrides step_start, start_warning_step, and start_error_step.
start_warning_step boolean false Go to the first step with a warning. Setting to true overrides step_start and start_error_step.
start_error_step boolean false Go to the first step with an error. Setting to true overrides step_start.
steps_onload function undefined Use the steps onload function to customize one time events that happen the first time a step is viewed. The function is called on each step, so checking if a step has a class of 'pstep#' is how you can make rules for specific steps in this one function. 

steps_onload: function(){
	cur_step = $(this);
	if (cur_step.hasClass('pstep1')
		// Do something awesome once.
}
steps_show function undefined The steps_show option is similar to the steps_onload function except that it runs every time you view a step. Be aware that this function executes after the step is showing (so events like focus will work on elements). 

steps_show: function(){
	cur_step = $(this);
	if (cur_step.hasClass('pstep1')
		// Do something awesome every time we load this step.
}
steps_hide function undefined The steps_hide option is similar to the steps_show function but it happens before hiding a step as we are transitioning away from it. 

steps_hide: function(){
	cur_step = $(this);
	if (cur_step.hasClass('pstep1')
		// Do something awesome every time we leave (hide) this step.
}
steps_transition function undefined This function is used for creating transitions between steps. It is ran before steps_hide. You need to add the class 'step-transition' to the step-title you are transitioning from for this to be called. You also need to add the class in this function 'step-transition-processing' to prevent the transition. Which ever step that was going to be transitioned to will have a 'step-resume' class on the title. Once you remove 'step-transition-processing and trigger the event go_to_step.psteps on the step-resume title, you'll have transitioned. This function definitely has a manual operation to it, but it is useful. You could always use the step-transition-processing class to stop transitions and just never manually start them up again. (Remember to remove the step-resume class if you do that.) 

steps_transition: function(){
	cur_step = $(this);
	cur_step.addClass('step-transition-processing');
	if (cur_step.hasClass('pstep1')
		// Do something awesome every time transition from this step.
}
validation_rule function return true This is the most important part of the plugin, because it is where you custom design the rules that will determine the progression and color indication of that progress. You will make all of your rules in this function, for each step. It's similar to the previous function examples, where we need to check if the step hasClass('pstep#') to make a rule for a certain step. 

validation_rule: function(){
	cur_step = $(this);
	if (cur_step.hasClass('pstep1')
		// Make a rule for step 1

	if (cur_step.hasClass('pstep2')
		// Make a rule for step 2.
}
The rule needs to return one of four options.
  1. return true - this will trigger the step complete and will, according to your options, allow progression to next step.
  2. return false - this will trigger the step incomplete and will, according to your options, not allow progression to next step.
  3. return 'warning' - this will trigger a warning and will always allow progression.
  4. return 'error' - this will trigger an error and will, according to your options, not allow progression.
If you have multiple rules within a single step, you would not want to return after the first check. You may consider just keeping a count of errors or warnings and then returning based on the final tally ( if you have any errors, return 'error'. If you have any warnings, return 'error'. See the practical use demo for an example of this or look at the code below. 

validation_rule: function(){
	cur_step = $(this);
	var incomplete = 0;
	var error = 0;
	if (cur_step.hasClass('pstep1') {
		var type_anything_input = cur_step.find('#type_anything_input');
		var type_bob_input = cur_step.find('#type_bob_input');
		if (type_anything_input == '') {
			incomplete++;
		}
		if (type_bob_input != '' && != 'bob')
			error++;
		else if (type_bob_input == '')
			incomplete++;

		if (error > 0)
			return 'error';
		else if (incomplete > 0)
			return false;
		else
			return true;
	}
}
validate_next_step boolean true Validate the current step before advancing to the next step. Must receive a return true from the validation rule.
validate_submit_all_steps boolean true Validate all steps before submitting. It looks at all step titles for any incomplete / errors[depending on other options]
validate_errors boolean true Validation for errors overrides validate_next_step. If this is false, and validate_next_step is true, progression to the next step would still not happen. (Because validate_next_step needs to receive a return true from the validation rule. So you may need to use ignore_errors_on_next if you really want to make validation for errors false.
ignore_errors_on_next boolean false Ignores validation errors on next when true. Useful for allowing progression on a test, but indicating that the answer was wrong. See the second circle demo.
ignore_errors_on_submit boolean false Option to ignore errors on submit-all (validate_submit_all_steps).
validate_error_msg string 'There was an error processing the step.' This error message will not be unique for errors on each step. It's generic. You can override it, but it still won't be unique. There's an option not to use it. Write your error alerts in your validation rule in that case.
validate_use_error_msg boolean true No validation message will show unless you define an alert in your validation rule.
use_before_submit boolean true If an alert/notice will be displayed to the user to indicate that they must complete all steps before submission.
before_submit string 'Please complete all of the required steps before submitting.' The alert/notice string to use to indicate to the user that they must complete all steps before submission.
use_before_next boolean true If an alert/notice will be displayed to the user to indicate that they must complete the current step before advancing to the next step.
before_next string 'Please complete this step before advancing to the next step.' The alert/notice string to use to indicate to the user that they must complete the current step before advancing to the next step.
btn_wait_class string 'btn-wait' The name of the class you want to use to execute the click function on the toggle buttons - next, back, submit - with a delay; good for giving time to the validation rule to wait on ajax calls.
btn_wait_time integer 1000 In milliseconds, the amount of time used to delay the click function applied to toggle buttons that have the btn_wait_class applied to them.
load_after_steps function undefined This function callback is triggered when the event "load_after_steps" is fired on the psteps object. Ideally you'd use this on the submit button. In the function you could write an ajax call to submit the form, but then display to the user a message, maybe depending on the success or failure of the ajax call to save the form contents. 

load_after_steps: function(){
	var psteps = $(this);
	psteps.find('.step-content').hide();
	psteps.find('.my_after_steps_content').html('Yay, you finished all the steps!').show();
	psteps.find('.back-button, '.submit-button').hide();
}
Also, look at the last circle layout demo. It makes use of this function very nicely.

Events

There are a few useful events you should know about when designing your Pines Steps! All of these events are done using trigger.

Example: 

$('SELECTOR').trigger('EVENT');
Event Description
validate.psteps This event fires on the psteps object and it will trigger the validation rule. It's useful to trigger this upon form element completion, so that progress is indicated instantly. $('#my_psteps').trigger('validate.psteps');
go_to_step.psteps This event needs to be fired on the step you want to go to. $('.pstep2', '#my_psteps').trigger('go_to_step.psteps');
go_to_first_incomplete.psteps This event should be fired on the psteps object. It will find the first incomplete step. $('#my_psteps').trigger('go_to_first_incomplete.psteps');
go_to_first_warning.psteps This event should be fired on the psteps object. It will find the first step with a warning. $('#my_psteps').trigger('go_to_first_warning.psteps');
go_to_first_error.psteps This event should be fired on the psteps object. It will find the first step with an error. $('#my_psteps').trigger('go_to_first_error.psteps');
traverse_never.psteps This event should be fired on the psteps object. It will change traversal of step titles to never. $('#my_psteps').trigger('traverse_never.psteps');
traverse_visited.psteps This event should be fired on the psteps object. It will change traversal of step titles to visited. $('#my_psteps').trigger('traverse_visited.psteps');
traverse_always.psteps This event should be fired on the psteps object. It will change traversal of step titles to always. $('#my_psteps').trigger('traverse_always.psteps');
traverse_custom.psteps This event should be fired on the psteps object. It will change traversal of step titles to custom. Specify your custom class in the options. I haven't used this, because I ended up adding the class step-notraverse to completed steps and left the setting on steps-visited. I prefer that because then I can let the plugin keep track of visited steps, but prevent certain ones from being re-visited. $('#my_psteps').trigger('traverse_custom.psteps');

Miscellaneous

What if you want different names for your next button? Or you want the submit button to show up on an earlier step but don't want it to flash the automatic hide from the plugin? Or you want to have some kind of transition between the steps? Or you want to prevent a next/submit button from going to the next step?

There are some classes you can add to certain elements to create some manual transitions and button names.

Class Description
step-transition Put this class on a step title in which you will transition from to signify that the steps_transition function will execute.
<div class="step-title step-transition"><span class="step-order">1</span><span class="step-name">Step 1</span></div>
step-transition-processing Add this class to a step-title during the steps_transition function to prevent automatic transitioning to the next step. The plugin will add the class 'step-resume' to the step title for the step that was prevented. Then use the event 'go_to_step.psteps' on the step-resume step in order to manually resume the step transition. Remember to remove this class before triggering! You could also use this class as a manual way to prevent going to the step. 
steps_transition: function(){
	cur_step = $(this);
	cur_step.addClass('step-transition-processing');
	if (cur_step.hasClass('pstep1')
		// Do something awesome every time transition from this step.
}
btn-manual Put this class on either the next-button, submit-button, or back-button. Should put the class on in the steps_show function. Should remove this class on the steps_hide function. This is so you can put any of these buttons on any step without seeing a flash or having issues with the button automatically being hidden. 
steps_show: function(){
	cur_step = $(this);
	if (cur_step.hasClass('pstep1') {
		// Showing Step 1
		form.find('.submit-button').addClass('btn-manual');
	}
}, steps_hide: function(){
	cur_step = $(this);
	if (cur_step.hasClass('pstep1') {
		// Hiding Step 1
		form.find('.submit-button').removeClass('btn-manual');
	}
}
btn-wait Put this class on either the next-button, submit-button, or back-button. Should put the class on in the steps_show function. Should remove this class on the steps_hide function. Use this with the options to change the class name to something else you prefer. You also use this with the btn_wait_time option, default 1000ms, to make the click function execute with a delay. Useful if you use ajax to validate/save and you need to wait to get back errors/warnings and do not want progression to happen right away (before ajax finishes). 
steps_show: function(){
	cur_step = $(this);
	if (cur_step.hasClass('pstep1') {
		// Showing Step 1
		form.find('.submit-button').addClass('btn-wait');
	}
}, steps_hide: function(){
	cur_step = $(this);
	if (cur_step.hasClass('pstep1') {
		// Hiding Step 1
		form.find('.submit-button').removeClass('btn-wait');
	}
}
step-notraverse Add this class to the step title of a step you do not want traversed. For example, you have traversal set to always, but do not want step 1 traversable. 
form.trigger('traverse_always.psteps')
form.find('.pstep1.step-title').addClass('step-notraverse');
Attribute Description
data-btn-name This attribute should be put on the button whose name you want to change. Let's say that the "next" button on step 1 should say "Sign Up". You would add the attribute data-btn-name and set it equal to "Sign Up" in the steps_show function. In the steps_hide function you would set the attribute to "Next" for all steps after the first step. 
steps_show: function(){
	cur_step = $(this);
	if (cur_step.hasClass('pstep1') {
		// Showing Step 1
		form.find('.next-button').attr('data-btn-name', 'Sign Up');
	}
}, steps_hide: function(){
	cur_step = $(this);
	if (cur_step.hasClass('pstep1') {
		// Hiding Step 1
		form.find('.next-button').attr('data-btn-name', 'Next');
	}
}

Theming

The Pines Steps plugin uses Twitter Bootstrap to style the progress indication. We recommend using Bootstrap to design the way your steps look and feel, as we've left it very flexible beyond the progress indication. Use Bootswatchr to create and download a custom theme for bootstrap that is easy to build and maintain.

Pines Steps comes with some really neat and useful includes. You should really consider using Font-Awesome in conjuction with bootstrap because it renders all of the icons as fonts, so they take on any font color and can be made any size. Look at the Font-Awesome project on Github. Two other plugins in the Pines project, PForm and PNotify are used in the Demos on this page are also included! PNotify is a fully customizable notification system that I've used in my demos to consume alerts. PForm is used on all form elements in my demos and is extremely flexible, crossbrowser efficient and fully semantic. Consider adapting these plugins into your projects!

Comments

comments powered by Disqus