github.com/emc-advanced-dev/unik@v0.0.0-20190717152701-a58d3e8e33b7/docs/examples/example-nodejs-fileserver/node_modules/serve-index/README.md (about)

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