JsFile

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

Installation

via NPM

You can install a jsFile package very easily using NPM. After installing NPM on your machine, simply run:

$ npm install jsfile

with Git

You can clone the whole repository with Git:

$ git clone git://github.com/jsFile/jsFile.git

from latest version

Also you can download the latest release of jsFile and include built files to your project.

Usage

You can include jsFile to your project in different ways:

as independent file from

<script src="path_to_js/dist/jsfile.js"></script>
<script>
    window.JsFile; //use an object in global namespace
</script>

as CommonJS module

var JsFile = require('JsFile');

as ES6 module

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);

API

JsFile

JsFile.version

Type: String

It's a current version of library.

JsFile.isSupported

Type: Boolean

It shows that jsFile can work in current browser or not.

JsFile.isSupported;

JsFile.mimeTypes

Type: Array

Contains list of supported mime-type in jsFile engines.

JsFile.mimeTypes; //[...supported mime-types...]

JsFile.defineEngine()

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.

JsFile.removeEngine(Engine)

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.

JsFile instance

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.

jf.read()

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

jf.findEngine()

Returns JsFile.Engine or null. This method finds an engine for jf.file.

jf.findEngine()

JsFile.Engine

JsFile.Engine.getCharFromHex(hex)

Returns a character from hex value.

JsFile.Engine.replaceSpaces(str)

Returns String. Replaces 2 and more spaces on \u2000\u2000 value.

JsFile.Engine.test()

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']
};

JsFile.Engine.normalizeDataUri(dataUri, filename)

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(name, options)

JsFile.Engine.formatPropertyName('namespace:prop'); //property
JsFile.Engine.formatPropertyName('prop-name'); //propName
JsFile.Engine.formatPropertyName('prop-name', {capitalize: true}); //PropName

JsFile.Engine.cropUnit(value)

JsFile.Engine.cropUnit('18px'); //18

JsFile.Engine.normalizeColorValue(value)

JsFile.Engine.normalizeColorValue('black'); //#000000
JsFile.Engine.normalizeColorValue('darkgreen'); //#006400

JsFile.Engine.attributeToBoolean(value)

JsFile.Engine.attributeToBoolean('yes'); //true
JsFile.Engine.attributeToBoolean('on'); //true
JsFile.Engine.attributeToBoolean('off'); //false
JsFile.Engine.normalizeColorValue({value: 1}); //true

JsFile.Engine.validateUrl()

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}

JsFile.Engine.merge()

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'   
}
*/

JsFile.Engine.clone()

Returns deep clone of object;

JsFile.Engine.errors

{Object}. List of constants with error messages

JsFile.Engine.prototype.isValid

Method of JsFile.Engine instance. Return true if file from engine is supported.

JsFile.Document

JsFile.Document.elementPrototype

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": ""
    }
}

doc.html()

Returns DocumentFragment with document content presented as HTML

const doc = new JsFile.Document(...);
doc.html();

doc.json()

Returns simple JS Object with parsed document tree

const doc = new JsFile.Document(...);
doc.json(); // {name: '', language: '', content: [...]}

doc.page()

Returns parsed page by index

const doc = new JsFile.Document(...);
doc.page(0);

doc.language

Returns main language of parsed document

const doc = new JsFile.Document(...);
doc.language; // String

doc.name

Returns name of parsed document

const doc = new JsFile.Document(...);
doc.name; // String

doc.wordsCount

Returns number of words in parsed document

const doc = new JsFile.Document(...);
doc.wordsCount; // Number

doc.length

Returns number of pages in parsed document

const doc = new JsFile.Document(...);
doc.length; // Number

doc.zoom

Returns zoom value of parsed document

const doc = new JsFile.Document(...);
doc.zoom; // Number

doc.isEmpty

Type: Boolean

const doc = new JsFile.Document(...);
doc.isEmpty; // Boolean

Tests

Clone JsFile sources via Git
Install dependencies. Just run the next command in JsFile directory:

$ npm install

Run tests task:

$ npm run tests

JsFile engines

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.)

Browser Support

Dependencies


43+ ✔	41+ ✔	32✔	8+ ✔

You can use polyfills for required API and try JsFile in older browsers.

Roadmap

Ongoing work

Improve performance of document parsing
Support .doc format
Add e2e tests
refactor zip engine

New features

Support .xslx format
Support .pptx format
Support .pdf
Support document editing and creation

Related projects

EasyDocs extension for browsers:
- Chrome

Help

You may support us:

Contribute

Guidelines

Code of conduct

JsFile is an open source project. Please read our code license

Found an Issue?

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.

Want a Feature?

You can request a new feature by submitting an issue to our GitHub Repository.

Code rules

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

Create custom engine

See the special generator for new jsFile engine . It will help you to start and provide required dependencies, structure and tools for jsFile engine.

Installing Dependencies

Git: The Github Guide to Installing Git is a good source of information
Node.js
Grunt

Forking JsFile on Github

To create a Github account, follow the instructions here. Afterwards, go ahead and fork the main JsFile repository.

Building JsFile

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

Running unit tests

npm run test

Release History

2015-08-12 v0.0.1 Release of the first version

Library submitted by @webschik

jsfile

JsFile

Installation

via NPM

with Git

from latest version

Usage

as independent file from

as CommonJS module

as ES6 module

API

JsFile

JsFile.version

JsFile.isSupported

JsFile.mimeTypes

JsFile.defineEngine()

JsFile.removeEngine(Engine)

JsFile instance

jf.read()

jf.findEngine()

JsFile.Engine

JsFile.Engine.getCharFromHex(hex)

JsFile.Engine.replaceSpaces(str)

JsFile.Engine.test()

JsFile.Engine.normalizeDataUri(dataUri, filename)

JsFile.Engine.formatPropertyName(name, options)

JsFile.Engine.cropUnit(value)

JsFile.Engine.normalizeColorValue(value)

JsFile.Engine.attributeToBoolean(value)

JsFile.Engine.validateUrl()

JsFile.Engine.merge()

JsFile.Engine.clone()

JsFile.Engine.errors

JsFile.Engine.prototype.isValid

JsFile.Document

JsFile.Document.elementPrototype

doc.html()

doc.json()

doc.page()

doc.language

doc.name

doc.wordsCount

doc.length

doc.zoom

doc.isEmpty

Tests

JsFile engines

Browser Support

Dependencies

Roadmap

Ongoing work

New features

Related projects

Help

Contribute

Guidelines

Code of conduct

Found an Issue?

Want a Feature?

Code rules

Create custom engine

Installing Dependencies

Forking JsFile on Github

Building JsFile

Running unit tests

Release History

Readme

Keywords

Package Sidebar

Install

Repository

Homepage

DownloadsWeekly Downloads

Version

License

Last publish

Collaborators

Weekly Downloads