Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

* README: updated all rdoc and package docs to 0.5 and its conventions.

  • Loading branch information...
commit 7f73c142373fe4a2ec4e6f108fa3ebc36c7b13bc 1 parent 3a96909
_why authored
View
14 CHANGELOG
@@ -1,3 +1,17 @@
+= 0.5
+=== 03 October, 2006
+
+* XHTML Validation built in. So, if you have an invalid tag: error. Invalid attribute: error.
+ And two identical IDs in the same document: error. Optional, of course. But handy!
+* New Markaby::Fragment class adds much flexibility. If it discovers you are using a tag as a string,
+ the tag is removed from the stream. (<tt>div { strong("Real") + " Giraffes" }</tt>)
+* The prevailing rule now is: if you want it escaped, pass it to a block. If not, pass it as an arg.
+* Again, escaped: <tt>h1("Me & You Have a Giraffe")</tt>
+* And, not escaped: <tt>h1 { "<a href='/'>Home</a>" }</tt>
+* Less method_missing, meaning: faster calls all around. Tag methods generated based on doctype.
+* The <tt>html</tt> method doesn't write the doctype tags and meta tags. You must use <tt>xhtml_transitional</tt> or <tt>xhtml_strict</tt> methods to do that.
+* The <tt>img</tt> method doesn't try to inject an empty alt tag and a zero border. No more of that.
+
= 0.3
=== 02nd February, 2006
View
131 README
@@ -73,44 +73,13 @@ This doesn't effect Rails users, but when used in regular Ruby code, it can
be a bit disorienting. You are recommended to put your Markaby code in a
module where it won't mix with anything.
-= A Note About Rails Helpers
-
-When used in Rails templates, the Rails helper object is passed into
-Markaby::Builder. When you call helper methods inside Markaby, the output
-from those methods will be output to the stream. This is incredibly
-handy, since most Rails helpers output HTML tags.
-
- head do
- javascript_include_tag 'prototype'
- autodiscovery_link_tag
- end
-
-However, some methods are designed to give back a String which you can use
-elsewhere. Call the <tt>@helpers</tt> object with the method and you'll get
-the String back and nothing will be output.
-
- p "Total is: #{@helper.number_to_human_size @file_bytes}"
-
-Conversely, you may call instance variables from your controller by using
-a method and its value will be returned, nothing will be output.
-
- # Inside imaginary ProductController
- def list
- @products = Product.find :all
- end
-
- # Inside app/views/product/list.mab
- products.each do |product|
- p product.title
- end
-
-= A Quick Tour
+= The Six Steps of Markaby
If you dive right into Markaby, it'll probably make good sense, but you're
-likely to run into a few kinks. Keep these pointers in mind and everything
-will be fine.
+likely to run into a few kinks. Why not review these six steps and commit
+them memory so you can really *know* what you're doing?
-== Element Classes
+== 1. Element Classes
Element classes may be added by hooking methods onto container elements:
@@ -128,7 +97,7 @@ Which results in:
<div class="entryContent">Okay, once again, the idea here is ...</div>
</div>
-== Element IDs
+== 2. Element IDs
IDs may be added by the use of bang methods:
@@ -146,18 +115,22 @@ Which results in:
</div>
</div>
-== Markaby assumes XHTML 1.0 Transitional
+== 3. Validate Your XHTML 1.0 Output
-Output defaults to XHTML 1.0 Transitional. To do XHTML 1.0 Strict,
-try this:
+If you'd like Markaby to help you assemble valid XHTML documents,
+you can use the <tt>xhtml_transitional</tt> or <tt>xhtml_strict</tt>
+methods in place of the normal <tt>html</tt> tag.
xhtml_strict do
- # innerds
+ head { ... }
+ body { ... }
end
-== Markaby prevents invalid HTML
+This will add the XML instruction and the doctype tag to your document.
+Also, a character set meta tag will be placed inside your <tt>head</tt>
+tag.
-Since Markaby knows which doctype you're using, it checks a big
+Now, since Markaby knows which doctype you're using, it checks a big
list of valid tags and attributes before printing anything.
>> div :styl => "padding: 10px" do
@@ -165,7 +138,38 @@ list of valid tags and attributes before printing anything.
>> end
InvalidHtmlError: no such attribute `styl'
-== Auto-stringification
+Markaby will also make sure you don't use the same element ID twice!
+
+== 4. Escape or No Escape?
+
+Markaby uses a simple convention for escaping stuff: if a string
+is an argument, it gets escaped. If the string is in a block, it
+doesn't.
+
+This is handy if you're using something like RedCloth or
+RDoc inside an element. Pass the string back through the block
+and it'll skip out of escaping.
+
+ div.comment { RedCloth.new(str).to_html }
+
+But, if we have some raw text that needs escaping, pass it in
+as an argument:
+
+ div.comment raw_str
+
+One caveat: if you have other tags inside a block, the string
+passed back will be ignored.
+
+ div.comment {
+ div.author "_why"
+ div.says "Torpedoooooes!"
+ "<div>Silence.</div>"
+ }
+
+The final div above won't appear in the output. You can't mix
+tag modes like that, friend.
+
+== 5. Auto-stringification
If you end up using any of your Markaby "tags" as a string, the
tag won't be output. It'll be up to you to add the new string
@@ -191,7 +195,7 @@ And any other operation you might perform on a string.
end.
join( " | " )
-== The <tt>tag!</tt> Method
+== 6. The <tt>tag!</tt> Method
If you need to force a tag at any time, call <tt>tag!</tt> with the
tag name followed by the possible arguments and block. The CssProxy
@@ -203,6 +207,45 @@ won't work with this technique.
end
end
+= A Note About Rails Helpers
+
+When used in Rails templates, the Rails helper object is passed into
+Markaby::Builder. When you call helper methods inside Markaby, the output
+from those methods will be output to the stream. This is incredibly
+handy, since most Rails helpers output HTML tags.
+
+ head do
+ javascript_include_tag 'prototype'
+ autodiscovery_link_tag
+ end
+
+However, some methods are designed to give back a String which you can use
+elsewhere. That's okay! Every method returns a Fragment object, which can
+be used as a string.
+
+ p { "Total is: #{number_to_human_size @file_bytes}" }
+
+Also see the Quick Tour above, specifically the stuff about auto-stringification.
+
+If for any reason you have trouble with fragments, you can just
+call the <tt>@helpers</tt> object with the method and you'll get
+the String back and nothing will be output.
+
+ p { "Total is: #{@helper.number_to_human_size @file_bytes}" }
+
+Conversely, you may call instance variables from your controller by using
+a method and its value will be returned, nothing will be output.
+
+ # Inside imaginary ProductController
+ def list
+ @products = Product.find :all
+ end
+
+ # Inside app/views/product/list.mab
+ products.each do |product|
+ p product.title
+ end
+
= Credits
Markaby is a work of immense hope by Tim Fletcher and why the lucky stiff.
View
2  Rakefile
@@ -8,7 +8,7 @@ require 'fileutils'
include FileUtils
REV = File.read(".svn/entries")[/committed-rev="(\d+)"/, 1] rescue nil
-VERS = ENV['VERSION'] || "0.4" + (REV ? ".#{REV}" : "")
+VERS = ENV['VERSION'] || "0.5" + (REV ? ".#{REV}" : "")
task :default => [:package]
View
2  lib/markaby.rb
@@ -19,7 +19,7 @@
# * Markaby::Template: a class for hooking Markaby into Rails as a
# proper templating language.
module Markaby
- VERSION = '0.4'
+ VERSION = '0.5'
class InvalidXhtmlError < Exception; end
end
View
33 lib/markaby/builder.rb
@@ -161,25 +161,23 @@ def tag!(tag, *args, &block)
f
end
- # Create XML markup based on the name of the method +sym+. This method is never
- # invoked directly, but is called for each markup method in the markup block.
- #
- # This method is also used to intercept calls to helper methods and instance
+ # This method is used to intercept calls to helper methods and instance
# variables. Here is the order of interception:
#
- # * If +sym+ is a recognized HTML tag, the tag is output
- # or a CssProxy is returned if no arguments are given.
- # * If +sym+ appears to be a self-closing tag, its block
- # is ignored, thus outputting a valid self-closing tag.
- # * If +sym+ is also the name of an instance variable, the
- # value of the instance variable is returned.
# * If +sym+ is a helper method, the helper method is called
# and output to the stream.
- # * Otherwise, +sym+ and its arguments are passed to tag!
+ # * If +sym+ is a Builder::XmlMarkup method, it is passed on to the builder object.
+ # * If +sym+ is also the name of an instance variable, the
+ # value of the instance variable is returned.
+ # * If +sym+ has come this far and no +tagset+ is found, +sym+ and its arguments are passed to tag!
+ # * If a tagset is found, though, +NoMethodError+ is raised.
+ #
+ # method_missing used to be the lynchpin in Markaby, but it's no longer used to handle
+ # HTML tags. See html_tag for that.
def method_missing(sym, *args, &block)
if @helpers.respond_to?(sym, true) && !self.class.ignored_helpers.include?(sym)
r = @helpers.send(sym, *args, &block)
- if @output_helpers
+ if @output_helpers and r.respond_to? :to_str
fragment { @builder << r }
else
r
@@ -195,6 +193,12 @@ def method_missing(sym, *args, &block)
end
end
+ # Every HTML tag method goes through an html_tag call. So, calling <tt>div</tt> is equivalent
+ # to calling <tt>html_tag(:div)</tt>. All HTML tags in Markaby's list are given generated wrappers
+ # for this method.
+ #
+ # If the @auto_validation setting is on, this method will check for many common mistakes which
+ # could lead to invalid XHTML.
def html_tag(sym, *args, &block)
if @auto_validation and @tagset.self_closing.include?(sym) and block
raise InvalidXhtmlError, "the `\#{sym}' element is self-closing, please remove the block"
@@ -262,6 +266,11 @@ def fragment
end
+ # Every tag method in Markaby returns a Fragment. If any method gets called on the Fragment,
+ # the tag is removed from the Markaby stream and given back as a string. Usually the fragment
+ # is never used, though, and the stream stays intact.
+ #
+ # For a more practical explanation, check out the README.
class Fragment < ::Builder::BlankSlate
def initialize(s, a, b)
@s, @f1, @f2 = s, a, b
View
12 lib/markaby/tags.rb
@@ -6,7 +6,7 @@ module Markaby
# Common sets of attributes.
AttrCore = [:id, :class, :style, :title]
- AttrI18n = [:lang, :'xml:lang', :dir]
+ AttrI18n = [:lang, 'xml:lang'.intern, :dir]
AttrEvents = [:onclick, :ondblclick, :onmousedown, :onmouseup, :onmouseover, :onmousemove,
:onmouseout, :onkeypress, :onkeydown, :onkeyup]
AttrFocus = [:accesskey, :tabindex, :onfocus, :onblur]
@@ -25,10 +25,10 @@ class << self
:head => AttrI18n + [:id, :profile],
:title => AttrI18n + [:id],
:base => [:href, :id],
- :meta => AttrI18n + [:id, :http, :name, :content, :scheme, :'http-equiv'],
+ :meta => AttrI18n + [:id, :http, :name, :content, :scheme, 'http-equiv'.intern],
:link => Attrs + [:charset, :href, :hreflang, :type, :rel, :rev, :media],
- :style => AttrI18n + [:id, :type, :media, :title, :'xml:space'],
- :script => [:id, :charset, :type, :src, :defer, :'xml:space'],
+ :style => AttrI18n + [:id, :type, :media, :title, 'xml:space'.intern],
+ :script => [:id, :charset, :type, :src, :defer, 'xml:space'.intern],
:noscript => Attrs,
:body => Attrs + [:onload, :onunload],
:div => Attrs,
@@ -41,13 +41,13 @@ class << self
:dd => Attrs,
:address => Attrs,
:hr => Attrs,
- :pre => Attrs + [:'xml:space'],
+ :pre => Attrs + ['xml:space'.intern],
:blockquote => Attrs + [:cite],
:ins => Attrs + [:cite, :datetime],
:del => Attrs + [:cite, :datetime],
:a => Attrs + AttrFocus + [:charset, :type, :name, :href, :hreflang, :rel, :rev, :shape, :coords],
:span => Attrs,
- :bdo => AttrCore + AttrEvents + [:lang, :'xml:lang', :dir],
+ :bdo => AttrCore + AttrEvents + [:lang, 'xml:lang'.intern, :dir],
:br => AttrCore,
:em => Attrs,
:strong => Attrs,
Please sign in to comment.
Something went wrong with that request. Please try again.