1 |
3a515b92
|
cagy
|
# serve-index
|
2 |
|
|
|
3 |
|
|
[![NPM Version][npm-image]][npm-url]
|
4 |
|
|
[![NPM Downloads][downloads-image]][downloads-url]
|
5 |
|
|
[![Linux Build][travis-image]][travis-url]
|
6 |
|
|
[![Windows Build][appveyor-image]][appveyor-url]
|
7 |
|
|
[![Test Coverage][coveralls-image]][coveralls-url]
|
8 |
|
|
[![Gratipay][gratipay-image]][gratipay-url]
|
9 |
|
|
|
10 |
|
|
Serves pages that contain directory listings for a given path.
|
11 |
|
|
|
12 |
|
|
## Install
|
13 |
|
|
|
14 |
|
|
This is a [Node.js](https://nodejs.org/en/) module available through the
|
15 |
|
|
[npm registry](https://www.npmjs.com/). Installation is done using the
|
16 |
|
|
[`npm install` command](https://docs.npmjs.com/getting-started/installing-npm-packages-locally):
|
17 |
|
|
|
18 |
|
|
```sh
|
19 |
|
|
$ npm install serve-index
|
20 |
|
|
```
|
21 |
|
|
|
22 |
|
|
## API
|
23 |
|
|
|
24 |
|
|
```js
|
25 |
|
|
var serveIndex = require('serve-index')
|
26 |
|
|
```
|
27 |
|
|
|
28 |
|
|
### serveIndex(path, options)
|
29 |
|
|
|
30 |
|
|
Returns middlware that serves an index of the directory in the given `path`.
|
31 |
|
|
|
32 |
|
|
The `path` is based off the `req.url` value, so a `req.url` of `'/some/dir`
|
33 |
|
|
with a `path` of `'public'` will look at `'public/some/dir'`. If you are using
|
34 |
|
|
something like `express`, you can change the URL "base" with `app.use` (see
|
35 |
|
|
the express example).
|
36 |
|
|
|
37 |
|
|
#### Options
|
38 |
|
|
|
39 |
|
|
Serve index accepts these properties in the options object.
|
40 |
|
|
|
41 |
|
|
##### filter
|
42 |
|
|
|
43 |
|
|
Apply this filter function to files. Defaults to `false`. The `filter` function
|
44 |
|
|
is called for each file, with the signature `filter(filename, index, files, dir)`
|
45 |
|
|
where `filename` is the name of the file, `index` is the array index, `files` is
|
46 |
|
|
the array of files and `dir` is the absolute path the file is located (and thus,
|
47 |
|
|
the directory the listing is for).
|
48 |
|
|
|
49 |
|
|
##### hidden
|
50 |
|
|
|
51 |
|
|
Display hidden (dot) files. Defaults to `false`.
|
52 |
|
|
|
53 |
|
|
##### icons
|
54 |
|
|
|
55 |
|
|
Display icons. Defaults to `false`.
|
56 |
|
|
|
57 |
|
|
##### stylesheet
|
58 |
|
|
|
59 |
|
|
Optional path to a CSS stylesheet. Defaults to a built-in stylesheet.
|
60 |
|
|
|
61 |
|
|
##### template
|
62 |
|
|
|
63 |
|
|
Optional path to an HTML template or a function that will render a HTML
|
64 |
|
|
string. Defaults to a built-in template.
|
65 |
|
|
|
66 |
|
|
When given a string, the string is used as a file path to load and then the
|
67 |
|
|
following tokens are replaced in templates:
|
68 |
|
|
|
69 |
|
|
* `{directory}` with the name of the directory.
|
70 |
|
|
* `{files}` with the HTML of an unordered list of file links.
|
71 |
|
|
* `{linked-path}` with the HTML of a link to the directory.
|
72 |
|
|
* `{style}` with the specified stylesheet and embedded images.
|
73 |
|
|
|
74 |
|
|
When given as a function, the function is called as `template(locals, callback)`
|
75 |
|
|
and it needs to invoke `callback(error, htmlString)`. The following are the
|
76 |
|
|
provided locals:
|
77 |
|
|
|
78 |
|
|
* `directory` is the directory being displayed (where `/` is the root).
|
79 |
|
|
* `displayIcons` is a Boolean for if icons should be rendered or not.
|
80 |
|
|
* `fileList` is a sorted array of files in the directory. The array contains
|
81 |
|
|
objects with the following properties:
|
82 |
|
|
- `name` is the relative name for the file.
|
83 |
|
|
- `stat` is a `fs.Stats` object for the file.
|
84 |
|
|
* `path` is the full filesystem path to `directory`.
|
85 |
|
|
* `style` is the default stylesheet or the contents of the `stylesheet` option.
|
86 |
|
|
* `viewName` is the view name provided by the `view` option.
|
87 |
|
|
|
88 |
|
|
##### view
|
89 |
|
|
|
90 |
|
|
Display mode. `tiles` and `details` are available. Defaults to `tiles`.
|
91 |
|
|
|
92 |
|
|
## Examples
|
93 |
|
|
|
94 |
|
|
### Serve directory indexes with vanilla node.js http server
|
95 |
|
|
|
96 |
|
|
```js
|
97 |
|
|
var finalhandler = require('finalhandler')
|
98 |
|
|
var http = require('http')
|
99 |
|
|
var serveIndex = require('serve-index')
|
100 |
|
|
var serveStatic = require('serve-static')
|
101 |
|
|
|
102 |
|
|
// Serve directory indexes for public/ftp folder (with icons)
|
103 |
|
|
var index = serveIndex('public/ftp', {'icons': true})
|
104 |
|
|
|
105 |
|
|
// Serve up public/ftp folder files
|
106 |
|
|
var serve = serveStatic('public/ftp')
|
107 |
|
|
|
108 |
|
|
// Create server
|
109 |
|
|
var server = http.createServer(function onRequest(req, res){
|
110 |
|
|
var done = finalhandler(req, res)
|
111 |
|
|
serve(req, res, function onNext(err) {
|
112 |
|
|
if (err) return done(err)
|
113 |
|
|
index(req, res, done)
|
114 |
|
|
})
|
115 |
|
|
})
|
116 |
|
|
|
117 |
|
|
// Listen
|
118 |
|
|
server.listen(3000)
|
119 |
|
|
```
|
120 |
|
|
|
121 |
|
|
### Serve directory indexes with express
|
122 |
|
|
|
123 |
|
|
```js
|
124 |
|
|
var express = require('express')
|
125 |
|
|
var serveIndex = require('serve-index')
|
126 |
|
|
|
127 |
|
|
var app = express()
|
128 |
|
|
|
129 |
|
|
// Serve URLs like /ftp/thing as public/ftp/thing
|
130 |
|
|
// The express.static serves the file contents
|
131 |
|
|
// The serveIndex is this module serving the directory
|
132 |
|
|
app.use('/ftp', express.static('public/ftp'), serveIndex('public/ftp', {'icons': true}))
|
133 |
|
|
|
134 |
|
|
// Listen
|
135 |
|
|
app.listen(3000)
|
136 |
|
|
```
|
137 |
|
|
|
138 |
|
|
## License
|
139 |
|
|
|
140 |
|
|
[MIT](LICENSE). The [Silk](http://www.famfamfam.com/lab/icons/silk/) icons
|
141 |
|
|
are created by/copyright of [FAMFAMFAM](http://www.famfamfam.com/).
|
142 |
|
|
|
143 |
|
|
[npm-image]: https://img.shields.io/npm/v/serve-index.svg
|
144 |
|
|
[npm-url]: https://npmjs.org/package/serve-index
|
145 |
|
|
[travis-image]: https://img.shields.io/travis/expressjs/serve-index/master.svg?label=linux
|
146 |
|
|
[travis-url]: https://travis-ci.org/expressjs/serve-index
|
147 |
|
|
[appveyor-image]: https://img.shields.io/appveyor/ci/dougwilson/serve-index/master.svg?label=windows
|
148 |
|
|
[appveyor-url]: https://ci.appveyor.com/project/dougwilson/serve-index
|
149 |
|
|
[coveralls-image]: https://img.shields.io/coveralls/expressjs/serve-index/master.svg
|
150 |
|
|
[coveralls-url]: https://coveralls.io/r/expressjs/serve-index?branch=master
|
151 |
|
|
[downloads-image]: https://img.shields.io/npm/dm/serve-index.svg
|
152 |
|
|
[downloads-url]: https://npmjs.org/package/serve-index
|
153 |
|
|
[gratipay-image]: https://img.shields.io/gratipay/dougwilson.svg
|
154 |
|
|
[gratipay-url]: https://www.gratipay.com/dougwilson/
|