2.3 HTML Resources

► |  | Scribble as Preprocessor

1 | Text Generation
2 | HTML Generation
| Index

▼ | 2 | HTML Generation

2.1 | Generating HTML Strings
2.2 | Generating XML Strings
2.3 | HTML Resources

On this page:

resource
url-roots
resource?
render-all
file-writer

Racket
top contents ← prev up next →

### 2.3 HTML Resources🔗ℹ

(require scribble/html/resource)
| package: scribble-html-lib

> procedure (resource path renderer [#:exists exists])
> | → |  |
> (and/c resource?
> (->* () (outputable/c) -> string?))
> path : string?
> renderer : (or/c (path-string? . -> . any) #f)
> exists : (or/c 'delete-file #f) = 'delete-file

Creates and returns a new resource value. Creating a resource registers renderer (if non-#f) to be called when rendering is initiated by render-all, while calling the result resource as a function generates a URL for the resource.

For example, a typical use of resource is to register the generation of a CSS file, where the value produced by resource itself renders as the URL for the generated CSS file. Another possible use of resource is to generate an HTML file, where the resource result renders as the URL of the generated HTML page.

The path argument specifies the path of the output file, relative to the working directory, indicating where the resource file should be placed. Though url-roots, path also determines the ultimate URL. The path string must be a /-separated relative path with no .., ., or //. The path string can end in /, in which case "index.html" is effectively added to the string. Using resource with #f as renderer is useful for converting a path to a URL according to url-roots.

The renderer argument (when non-#f) renders the resource, receiving the path for the file to be created. The path provided to renderer will be different from path, because the function is invoked in the target directory.

The resulting resource value is a function that returns the URL for the resource. The function accepts an optional boolean; if a true value is provided, the result is an absolute URL, instead of relative. Note that the function can be used as a value for output, which uses the resource value as a thunk (that renders as the relative URL for the resource). The default relative resulting URL is, of course, a value that depends on the currently rendered resource that uses this value.

When renderer is called by render-all, more resources can be created while rendering; the newly created resources will also be rendered, in turn, until no more new resources are created.

If exists is 'delete-file and the target file exists when renderer is to be called, then the file is deleted before renderer is called.

> parameter (url-roots)
> | → |  |
> (or/c #f
> (listof (cons/c path-string?
> (cons/c string?
> (listof (or/c 'abs 'index))))))
> (url-roots roots) → void?
> | roots |  | : |  |
> (or/c #f
> (listof (cons/c path-string?
> (cons/c string?
> (listof (or/c 'abs 'index))))))

A parameter that determines how resource paths are converted to URLs for reference. A #f value is equivalent to an empty list.

The parameter value is a mapping from path prefixes to URLs (actually, any string). When two paths have the same prefix, links from one to the other are relative (unless absolute links are requested); if they have different prefixes, the full URL is used. The paths enclosed by two root paths must be disjoint (e.g., the list must not include both "/colors" and "/colors/red", but it can include both "/colors/red" and "/colors/blue").

If an item in the parameter’s list includes 'abs, then a site-local, absolute URL (i.e., a URL that starts with /) is produced for references among files within the corresponding prefix.

If an item in the parameter’s list includes 'index, then a reference to a directory path is converted to a reference to "index.html", otherwise a reference to "index.html" is converted to a directory path.

> procedure (resource? v) → boolean?
> v : any/c

Returns #t if v is a procedure (that takes 0 or 1 arguments) produced by resource.

> procedure (render-all) → void?

Generates all resources registered via resource.

> procedure (file-writer content-writer content) → (path-string? . -> . any)
> content-writer : (outputable/c output-port? . -> . any)
> content : outputable/c

Produces a function that is useful as a writer argument to resource. Given a path, the produced function writes content to the path by passing content and an output port for the file to content-writer.
top contents ← prev up next →