Source

hh-web-tags / package.lisp

Full commit
;; Copyright (c) 2010 Phil Hargett

;; Permission is hereby granted, free of charge, to any person obtaining a copy
;; of this software and associated documentation files (the "Software"), to deal
;; in the Software without restriction, including without limitation the rights
;; to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
;; copies of the Software, and to permit persons to whom the Software is
;; furnished to do so, subject to the following conditions:

;; The above copyright notice and this permission notice shall be included in
;; all copies or substantial portions of the Software.

;; THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
;; IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
;; FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
;; AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
;; LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
;; OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
;; THE SOFTWARE.

(defpackage #:hh-web-tags-asd
  (:use :cl :asdf))

(in-package :hh-web-tags-asd)

(defpackage :hh-web-tags
  (:nicknames :wt)
  (:use :cl :local-time :vecto)
  (:export
   
   ;; For tags

   #:defhtmltag
   #:defentity
   #:hout
   #:*current-tag*
   #:*this-tag*
   #:*tag-library-registry*
   #:call-next-tag-method

   #:_body
   #:body-of
   #:style-of 
   #:html-id
   #:css-class
   #:style-of
   #:rel-of
   #:id
   #:class
   #:style
   #:rel

   #:htmltag
   #:render-as-html

   #:+@
   #:+title
   #:+link

   #:expansion
   #:tags

   #:html
   #:page
   #:with-tag-reader

   ;; For tag libraries
  #:*tag-library*
  #:*tag-library-provider-registry*
  #:*package-template-folder*
  #:*package-tag-library-folder*
  #:*template*
  #:*minimum-template-stale-time*
  #:create-folder-tag-library-provider
  #:create-asdf-system-tag-library-provider

  #:in-tag-library
  #:use-tag-library
  #:+tag-library
  #:local-tag-library-provider-registry-symbol
  
  ;; For templates
  #:template
  #:deftemplate
  #:deftemplates
  #:*template*
  #:*template-provider-registry*
  #:create-folder-template-provider
  #:create-asdf-system-template-provider
  #:local-template-provider-registry-symbol

   )
  (:documentation "HH-WEB-TAGS is an HTML generation library.  What separates this library from some others is
   that the library coordinates in a modular fashion the generation of not just HTML, but also CSS, Javascript, 
   and other meta-data on a page.  

   It does so by defining the concept of a $(em \"tag\"), which may have associated HTML, CSS, Javascript,
   etc.  Embedding the tag onto a page will cause the library to include the HTML, CSS, Javascript, etc., from the tag
   into the final generated HTML output.  If the same tag appears multiple times, only a single copy of the relevant CSS
   and Javascript appears in the output.  Tags use typical Lisp s-expression syntax (e.g., parentheses) with attributes
   expressed as keyword arguments inside of braces (e.g., { }) instead of the angle brackets (e.g., < > ) of HTML.  Thus:
 

    (div 
     (p {:id \"description\"} 
       \"A foo is the best widget for all your bar needs.\")))


   instead of:

   $(literal (div 
     (p {:id \"description\"} 
       \"A foo is the best widget for all your bar needs.\"))) 

   TAGS

   A tag provides a unit of modularity, allowing the developer to focus strictly on small units of functionality, and 
   HH-WEB-TAGS makes composition of tags into a larger page a straightforward matter.  It's precisely this modularity
   that's often missing from web development: to implement a portion of page, one has to insert HTML in the body, 
   write script in the head, add a list of required script libraries, update CSS styles, etc.  HH-WEB-TAGS handles all
   of that, extracting the relevant parts from a tag definition and inserting them intelligently in the final output.

   The $(a {:href \"#_macro_defhtmltag\"} \"defhtmltag\") macro is used to define tags, and tags can refer to other tags
   when describing the content the tag can generate.  Further, all attributes of a tag are available as variables (actually,
   as symbol macros defined by symbol-macrolet) within the body of the content, so parameterized generation of content is 
   straightforward.

   In the context of HTML generation (e.g., within the body of a template, below, or in an s-expression passed to the
   $(a {:href \"#_macro_html\"} \"html\") macro), using a tag is just like using any other function or macro.  Tags themselves
   are evaluated as macros literally by wrapping a macrolet around the form from which one wishes to generate HTML.  An 
   attribute list is completely optional, and can be placed inside either braces { } or a (+@ ) form.  HH-WEB-TAGS uses a 
   custom readtable to expand the former representation into the latter.  Tags are macros (rather than functions) for the
   simple reason that each 'outer' tag establishes some context in which each 'inner' tag is evaluated.  The body of a tag
   (e.g., the rest of the tag's arguments, minus the attribute list) is eventually evaluated and becomes a list attached to the tag 
   as it's content.  Any combination of lists, tags, strings, numbers, or other Lisp types are valid, provided they 
   have a printable representation.  

   As an aid to mixing text content and HTML markup, during HTML generation, any string is scanned for occurrences of a dollar-sign 
   ($$) character: any such occurrence should be followed immediately by an s-expression, and the result of evaluating that expression 
   will be written into the generated HTML, rather than the literal expression.  To use a dollar-sign literal instead, use 2 dollar-signs
   in succession ($$$$).

   TAG LIBRARIES

   In addition to tags, the other primary concepts that HH-WEB-TAGS defines are tag libraries and templates.  Tag libraries are just
   collections of related tag definitions; a basic HTML library is included in HH-WEB-TAGS.  Every tag has an associated 
   symbol, and each tag library defines a Lisp package containing those symbols.  A tag library is just an ordinary file
   containing Lisp expressions (so defuns, defvars, and other standard Lisp expressions are all still valid), except that
   any occurrences of $(a {:href \"_macro_defhtmltag\"} \"defhtmltag\") become tag definitions associated with that tag library.

   TEMPLATES

   Templates build up complete web pages from tags.  

   Additionally, it defines the concept of a $(em \"template\"), a parameterizable description of a single web page
   (or other web resource, actually; see images below).  Instead of writing a page (or template) in raw HTML, one writes
   a template using tags, either from the built-in HTML tag library or a custom tag library.

   ENTITIES

   HH-WEB-TAGS also supports HTML entities, and defines many standard HTML entities directly in the HTML tag library. Ideally,
   all needed HTML entities are already available in the built-in tag library, but if not, one can use the $(a {:href \"_macro_defentity\"} \"defentity\") 
   macro  to define new ones, or to add entities still missing from the HTML tag library.

"))