Source

pyramid_uniform / pyramid_uniform / templates / static / readme

Uni-Form by Dragan Babic [Superawesome Industries]  - http: //sprawsm.com/uni-form/
Some rights reserved - http: //creativecommons.org/licenses/by-sa/2.5/

Thank you for downloading Uni-Form!

========================================================

INTRO

Uni-Form is an attempt to standardize form markup (xhtml), css and JavaScript,  modularize it, so even people with only basic knowledge of these technologies can get nice looking, well structured, highly customizable, semantic, accessible and usable forms.
The main goal is to make the whole thing as much plug n play as possible, literally reduce the whole process of form creation to copy and paste technique. The result currently works in the following browsers:

    * IE6
    * IE7
    * Firefox
    * Opera9.x
    * Safari
    * Camino
    * Konqueror

========================================================

HOW DOES IT WORK?

The whole idea came from the Microformats (http://microformats.org/) movement and various ideas for standardizing form markup and it’s nomenclature. Forms in html are somewhat specific and kind of a „gray area” for developers, designers especially, elements are inflexible, crude, and basically it is the „soft spot” of html. Not many people know how to mark up their forms properly and semantically, so hopefully this will be of help to them - and in turn - also to people who will eventually be using those forms. 
Basically all you need to do is apply a few classes here and there and copy and paste special snippets of code (called units) that you need for your form. 

========================================================

GETTING STARTED:

NOTE: Uni-Form will work out of the box, but in order to get real control over your design and form layout, it requires a good amount of familliarity with CSS and of course - you'll have to dive into the code. It is primarily a tool for developers. 

  - Linking the files:
    1) Download the most recent version of Uni-Form from http://sprawsm.com/uni-form/
    2) Unpack and upload to your server into appropriate directories (e.g. place the css files in a dir called css, JavaScript files into a dir called js...)
    3) Now you need to link the uni-form.css with you html document, you do that with this piece of code: 
         <style type="text/css" media="screen"> 
           @import "path/to/directory/uni-form.css"; 
         </style>
    4) If you want to include JavaScript behavior to your form, you need to link the JS files as well, you do that with these two following lines of code: 
         <script src="path/to/directory/js/jquery.js" type="text/javascript"></script>
         <script src="path/to/directory/js/uni-form.jquery.js" type="text/javascript"></script>
         (NOTE: As of version 1.2 Uni-Form is using jQuery (http://jquery.com/) for all behavior.)
  - Prepping the form:
    Your form element that will be your Uni-Form should have a class .uniForm, so your opening form tag could look something like this: 
      <form action="/" method="whatever" id="whatever" class="uniForm">
      Next thing you need to do is to add the classes .inlineLabels or .blockLabels to the fieldset elements (or to the wrapping div inside the form) in your form to get the desired layout.
  
========================================================

UNI-FORM UNITS:

Units are code snippets that you just copy and paste into your form, please note that you will most probably have to update form fields IDs and names respectfully. Here are the so far available out of the box Uni-Form units: 
    
    1) Text input: 
    <div class="ctrlHolder">
      <label for="password">Choose Password</label>
      <input name="password" id="password" value="" size="35" maxlength="25" type="password" class="textInput" />
    </div>
    --
    2) Textarea: 
    <div class="ctrlHolder">
      <label for="skills_interests">Skills and interests</label>
      <textarea name="skills_interests" id="skills_interests" rows="25" cols="25"></textarea>
    </div>
    --
    3) Select box: 
    <div class="ctrlHolder">
      <label for="dob_m">Date of birth</label>
      <select name="dob_m"  id="dob_m" class="selectInput">
        <option value="">-- Month --</option>
        <option value="01">January</option><option value="02">February</option><option value="03">March</option><option value="04">April</option><option value="05">May</option><option value="06">June</option><option value="07">July</option><option value="08">August</option><option value="09">September</option><option value="10">October</option><option value="11">November</option><option value="12">December</option>
      </select>
    </div>
    --
    4) Check box: 
    <div class="ctrlHolder">
      <label for="newsletter" class="inlineLabel"><input name="newsletter" id="newsletter" value="1" type="checkbox" /> Send me your news and information (a.k.a. junk)</label>
    </div>
    --
    5) Radio button: 
    <div class="ctrlHolder">
      <div>
        <label for="newsletter" class="inlineLabel"><input name="newsletter" id="newsletter" value="1" type="radio" /> Send me your news and information (a.k.a. junk)</label>
      </div>
    </div>
    --
    6) Multiple checkboxes with a caption (these can be radios as well, using checkboxes just to illustrate):
    <div class="ctrlHolder">
      <p class="label">
        Display options:
      </p>
      <div class="multiField">
        <label for="display_email" class="inlineLabel"><input name="display_email" id="display_email" value="1" type="checkbox" /> Display my email</label>
        <label for="display_photo" class="inlineLabel"><input name="display_photo" id="display_photo" value="1" type="checkbox" /> Display my image</label>
      </div>
    </div>
    --
    7) Multiple select boxes (e.g. for dates)
    <div class="ctrlHolder">
      <p class="label">
        <em>*</em> Combo Field
      </p>
      <div class="multiField">
        <label for="dob_month" class="blockLabel"><span>Month</span> <select id="dob_month" name="dob_month"><option value="1">January</option></select></label>
        <label for="dob_day" class="blockLabel"><span>Day</span> <select id="dob_day" name="dob_day"><option value="1">1</option></select></label>
        <label for="dob_year" class="blockLabel"><span>Year</span> <select id="dob_year" name="dob_year"><option value="1">1908</option></select></label>
      </div>
    </div>
    --
    8) Multiple input boxes (e.g. for phone numbers)
    <div class="ctrlHolder">
      <p class="label">
        <em>*</em> Phone Number
      </p>
      <div class="multiField phoneNum"> <!-- I have added a class .phoneNum as a hook to this .multiField so I can target it's children precisely, but it's not a part of Uni-Form -->
        <label for="phone_ccode" class="blockLabel">Country <input type="text" id="phone_ccode" name="phone_ccode" size="20" value="" class="textInput" /></label>
        <label for="phone_area" class="blockLabel">Area <input type="text" id="phone_area" name="phone_area" size="20" value="" class="textInput" /></label>
        <label for="phone_num" class="blockLabel">Phone number<input type="text" id="phone_num" name="phone_num" size="20" value="" class="textInput" /></label>
      </div>
    </div>
    --
    9) Upload file field:
    <div class="ctrlHolder">
      <label for="new_image"><em>*</em> Upload Picture</label>
      <input name="new_image" id="new_image" size="30" type="file" class="fileUpload" />
    </div>
    --
    10) Submit buttons:
    <div class="buttonHolder">
      <button type="submit" class="submitButton">Submit</button>
    </div>
    
    or if you need a reset button (or any other button for that matter) as well: 
    
    <div class="buttonHolder">
      <button type="reset" class="resetButton">Reset</button>
      <button type="submit" class="submitButton">Submit</button>
    </div>

  - Form hints and required fields indication: 
  
    Uni-Form offers a nice way to hint to your users what kind of input is expected in a form field. These hints can be safely omitted if you don't need them. To add a hint, just add a paragraph (p element) with a class of .formHint right before the closing div.ctrlHolder tag. 
    
    Also, a very important part of any form is indicating required fields (although it would be wise to group those in their own fieldset), and it is sort of a convention to indicate those fields with an asterisk character. At the beginning of a label just place an asterisk in an emphasis element (em) and you're all set. 
    
Take a look at the demo form below for an example usage of Uni-Form and these two additional conveniences - hints and required fields indicators. 

========================================================

Example: 

For the sake of clarity, here is a simple demonstration of how a Uni-Form should look like. We'll use a contact form as one of the simplest examples: 

<form class="uniForm" action="contact.php" method="post"> 

  <fieldset class="inlineLabels">

    <legend>Contact Details</legend> 

    <!-- Uni-Form units start -->
    <div class="ctrlHolder">
      <label for="name"><em>*</em> Name</label>
      <input name="name" id="name" value="" size="35" maxlength="25" type="text" class="textInput" />
      <p class="formHint">
        Your real name or your company's name. 
      </p>
    </div>

    <div class="ctrlHolder">
      <label for="email"><em>*</em> Email</label>
      <input name="email" id="email" value="" size="35" maxlength="25" type="text" class="textInput" />
      <p class="formHint">
        Will be used only to reply to you. Will not be passed on to a third party. Enter a valid email account. 
      </p>
    </div>

    <div class="ctrlHolder">
      <label for="message">Message</label>
      <textarea name="message" id="message" rows="25" cols="25"></textarea>
      <p class="formHint">
        Write your message to us here. HTML is not allowed, plain text only please. 
      </p>
    </div>
    <!-- Uni-Form units end -->
  
  </fieldset>

</form> 

========================================================

COLUMNS: 

Support for columnar layouts indeed does exist, but at a very primitive level. Basically columns should be divs with a class .col, along with the first and last divs having two additional classes .first and .last respectfully. They will all be floated to the left, apart from the last column that will be floated to the right and stripped off of it's right margin. 

========================================================

LEGALESE: 

This project is released under a Creative Commons License (http://creativecommons.org/licenses/by-sa/2.5/) so certain limitations apply. That basically means that you can do whatever you want with this (redistribute, alter, whatever...), as long as you continue to share it with this same license and attribute me - Dragan Babić - as the original author (author on who's derrivative work your version is based on). 

Thank you for using Uni-Form, give respect and get it back. 
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.