# = HTML utilities collection
#
# code:: gmosx, tkout, ekarak
#
# (c) 2004 Navel, all rights reserved.
# $Id: html.rb 71 2004-10-18 10:50:22Z gmosx $

require "uri"
require "cgi"

module N;

# = HtmlUtils
#
# === Design:
#
# Implement as a module to avoid class polution. You can still Ruby's
# advanced features to include the module in your class.
# Passing the object to act upon allows to check for nil, which isn't
# possible if you use self.
#
# The older text_sum, text_block methods are not needed in the latest
# code
#
# === TODO:
# - add xxx! versions
#
module HtmlUtils

	# escape html tags.
	# usefull to make text entered by end users html safe.
	#
	# Input:
	# the string to be escaped
	#
	# Output:
	# the escaped string
	#
	def self.escape(string)
		# gmosx: no need to return "" on nil, will be interpolated to ""
		return nil unless string
		return CGI::escapeHTML(string)
	end

	# TODO: move to markup!
	#
	# Expands the urls found in the given string. Use the target parameter
	# to apply presentation semantics (ie open in new window)
	#
	# Example:
	#  text = "visit this site: www.navel.gr"
	#  text = Web::Utils::Html::expand_urls(text)
	#  p text # =>
	# "visit this site: <a href='http://www.navel.gr'>http://www.navel.gr</a>"
	#
	def self.expand_urls(string, target = nil)
		return nil unless string

		xstring = string.gsub(/\s(www\.[^\s]*)/, " http://\\1")
		xstring.gsub!(/\s(ftp\.[^\s]*)/, " ftp://\\1")

		xstring.gsub!(URI::REGEXP::ABS_URI_REF) { |uriref|
			if /(http|ftp):/.match(uriref)
				"<a" + (target.nil?? "" : " target='#{target}'") +
						" href='#{uriref}'>#{uriref}</a>"
			else
				uriref
			end
		}

		return xstring
	end

	# Strips potentially dangerous html tags, leaving only safe
	# tags. Usefull for simple Html formatting.
	#
	# === Design:
	#
	# Escapes ALL quotes for security, use html without quotes:
	#
	# <font size=+1>kok</font>
	# <a href=http://www.navel.gr
	# ...
	#
	# Should handle the following case:
	#
	# <tr><td><a href='koko</td></tr>...
	# passes with obvious results :(
	# even the following fucks up browsers:
	# <tr><td><p href='koko</td></tr>
	#
	# We HAVE TO CHECK VALID XHTML/XML before using this method.
	#
	# <img> is NOT a safe tag, because it can fuckup the
	# layout, so it is not included in the default safe tags
	#
	# on open
	#
	# === Input:
	# the string to be filtered
	# extra exclude_tags
	# extra include_tags
	#
	# === Output:
	# the filtered string, only contains safe html tags

	OPEN_TAGS = /<([^<>]*)(?=<)/
	VALID_TAGS = /<([^<>]*)>(?=<)/
	OPEN_QUOTES = /['"]([^'"]*)(?!['"])/

	def self.only_safe_tags(string, exclude_tags = nil, include_tags = nil)
		return nil unless string

		# default safe tags
		# FIXME: move the array outside of the method to avoid
		# excessive array creation

		safe_tags = ["A", "B", "I", "U", "BR", "STRONG", "LI"]

		# customize if necessary
		safe_tags += exclude_tags if exclude_tags
		safe_tags -= include_tags if include_tags

        # try to fix up invalid XHTML tags: close brackets, and
		# escape quotes of open tags.
		# SOS: keep the order of the escapes!

		escaped = string.gsub(OPEN_TAGS, '<\1>')
		escaped = CGI::escapeHTML(escaped)
		escaped =  CGI::unescapeElement(escaped, safe_tags)
		escaped.gsub!(/"/, '&quot;')
		escaped.gsub!(/'/, '&#39;')

		return escaped
	end

	# convert plain newlines into line breaks <br/>

	def self.convert_newlines(string)
		return nil unless N::StringUtils.valid?(string)
		xstring = string.gsub(/\n/, "<br/>")
		return xstring;
	end
		
end

end # module