JavaScript library for working with files in browser. See demo on https://jsfile.github.io/jsFile/
- Installation
- Usage
- API
- JsFile
- JsFile.Engine
- JsFile.Document
- Tests
- JsFile engines
- Examples
- Browser support
- Roadmap
- Help
- Contribute
- Create custom engine
You can install a jsFile
package very easily using NPM. After
installing NPM on your machine, simply run:
$ npm install jsfile
You can clone the whole repository with Git:
$ git clone git://github.com/jsFile/jsFile.git
Also you can download the latest release of jsFile
and include built files to your project.
You can include jsFile to your project in different ways:
<script src="path_to_js/dist/jsfile.js"></script>
<script>
window.JsFile; //use an object in global namespace
</script>
var JsFile = require('JsFile');
import JsFile from 'JsFile';
Include one or more engines for necessary file types. See all list of engines
import JsFile from 'JsFile';
import JsFileDsv from 'jsfile-dsv'; //read .csv
import JsFileOoxml from 'jsfile-ooxml'; //read .docx
JsFile.defineEngine(JsFileDsv);
JsFile.defineEngine(JsFileOoxml);
const jf = new JsFile(file, options);
Type: String
It's a current version of library.
Type: Boolean
It shows that jsFile
can work in current browser or not.
JsFile.isSupported;
Type: Array
Contains list of supported mime-type in jsFile engines.
JsFile.mimeTypes; //[...supported mime-types...]
Returns JsFile.Engine object or null
(if engine is invalid).
You can create your own documents engine for jsFile
and include it to the library.
JsFile.defineEngine(Engine);
Engine {Function}
- it's an inherited class
from JsFile.Engine.
It must have static property mimeTypes
(array with supported mime types) and static method test
to test which type of file is supported.
Engine {Function}
- it's an inherited class
from JsFile.Engine.
It removes specified Engine
from defined engines. If Engine
argument isn't defined it removes all defined engines.
In the next examples I will use JsFile
instance:
let jf = new JsFile(file[, options]);
file {File|Blob} [required]
(Read about File or Blob)
options {Object} [optional]
- object with your custom settings:
workerPath {String}
- path to Web Worker files.
Returns Promise object
jf.read().then(
(document) => {...your success handler...},
(error) => {...your error handler...}
);
error
{Error} - object contains description of the error in error.message
property
document
- object contains result of file reading. For more details see JsFile.Document
Returns JsFile.Engine or null
. This method finds an engine for jf.file
.
jf.findEngine()
Returns a character from hex
value.
Returns String
.
Replaces 2 and more spaces on \u2000\u2000
value.
Returns Boolean
.
If you develop a custom JsFile engine, you should override this method:
static test (file) {
return Boolean(file && Engine.validateFile(file, files));
}
files
- Object with meta-information about supported formats:
// Example for FB2 engine:
const files = {
extension: ['fb2'],
mime: ['application/x-fictionbook+xml']
};
Normalizes a dataUri
string according to specified filename
.
const dataUri = 'data:;base64,....';
const filename = 'test.png';
JsFile.Engine.normalizeDataUri(dataUri, filename); //data:image/png;base64,...
JsFile.Engine.formatPropertyName('namespace:prop'); //property
JsFile.Engine.formatPropertyName('prop-name'); //propName
JsFile.Engine.formatPropertyName('prop-name', {capitalize: true}); //PropName
JsFile.Engine.cropUnit('18px'); //18
JsFile.Engine.normalizeColorValue('black'); //#000000
JsFile.Engine.normalizeColorValue('darkgreen'); //#006400
JsFile.Engine.attributeToBoolean('yes'); //true
JsFile.Engine.attributeToBoolean('on'); //true
JsFile.Engine.attributeToBoolean('off'); //false
JsFile.Engine.normalizeColorValue({value: 1}); //true
Returns Boolean
value. It's utility method for URL validation. Might be helpful in development of custom engines
let engine = new JsFile.defineEngine(...);
engine.validateUrl(url); // true or false
url {String}
Deep merge of objects;
const a = {
data: {
value: 1
},
name: 'test'
};
const b = {
data: {
value: 0
}
};
JsFile.Engine.merge(a, b);
/*
It returns:
{
data: {
value: 0
},
name: 'test'
}
*/
Returns deep clone of object;
{Object}. List of constants with error messages
Method of JsFile.Engine
instance. Return true if file from engine is supported.
Type: Object
It is a static property that contains the base structure for each element of parsed document
{
"children": [],
"style": {
"position": "relative",
"boxSizing": "border-box"
},
"properties": {
"tagName": "DIV",
"textContent": ""
}
}
Returns DocumentFragment with document content presented as HTML
const doc = new JsFile.Document(...);
doc.html();
Returns simple JS Object
with parsed document tree
const doc = new JsFile.Document(...);
doc.json(); // {name: '', language: '', content: [...]}
Returns parsed page by index
const doc = new JsFile.Document(...);
doc.page(0);
Returns main language of parsed document
const doc = new JsFile.Document(...);
doc.language; // String
Returns name of parsed document
const doc = new JsFile.Document(...);
doc.name; // String
Returns number of words in parsed document
const doc = new JsFile.Document(...);
doc.wordsCount; // Number
Returns number of pages in parsed document
const doc = new JsFile.Document(...);
doc.length; // Number
Returns zoom value of parsed document
const doc = new JsFile.Document(...);
doc.zoom; // Number
Type: Boolean
const doc = new JsFile.Document(...);
doc.isEmpty; // Boolean
- Clone JsFile sources via Git
- Install dependencies. Just run the next command in JsFile directory:
$ npm install
- Run tests task:
$ npm run tests
- jsFile-ooxml for Office Open XML format (.docx files, etc.)
- jsFile-odf for OpenDocument format (.odf files, etc.)
- jsFile-rtf for Rich Text Format (.rtf files)
- jsFile-wcbff for Windows Compound File Binary format (.doc files, etc.)
- jsFile-fb for FictionBook format (.fb2 files, etc.)
- jsFile-dsv for Delimiter-separated values format (.csv, .tsv files, etc.)
- jsFile-image works with many image formats
- jsFile-txt process the file as a simple text
- jsFile-epub for EPUB format (.epub files, etc.)
- Promise
- Web Workers
- File
- Blob
- FileReader
- ArrayBuffer
- Uint8Array
- DataView
- zip.js (see
src/zip/
folder)
| |
|
|
|
|:---:|:---:|:---:|:---:|:---:|
| 43+ ✔ | 41+ ✔ | 32✔ | 8+ ✔ |
You can use polyfills for required API and try JsFile
in older browsers.
- Improve performance of document parsing
- Support .doc format
- Add e2e tests
- refactor zip engine
- Support .xslx format
- Support .pptx format
- Support .pdf
- Support document editing and creation
EasyDocs
extension for browsers:
You may support us:
JsFile is an open source project. Please read our code license
If you find a bug in the source code or a mistake in the documentation, you can help us by submitting an issue to our GitHub Repository. Even better you can submit a Pull Request with a fix.
You can request a new feature by submitting an issue to our GitHub Repository.
- All features or bug fixes must be tested by one or more specs.
- All public API methods must be documented with jsdoc
- We use ES6 (EcmaScript2015) in JsFile
- See our jscs configuration
See the special generator for new jsFile engine . It will help you to start and provide required dependencies, structure and tools for jsFile engine.
- Git: The Github Guide to Installing Git is a good source of information
- Node.js
- Grunt
To create a Github account, follow the instructions here. Afterwards, go ahead and fork the main JsFile repository.
- Install JsFile with Git
- Follow the next steps:
#Go to the JsFile directory:
cd jsfile
#Add the main JsFile repository as an upstream remote to your repository:
git remote add upstream "https://github.com/jsFile/jsFile.git"
#Install node.js dependencies:
npm install
#Build JsFile:
grunt build
npm run test
- 2015-08-12 v0.0.1 Release of the first version
Library submitted by @webschik