Skip to content

Commit 331f77b

Browse files
author
Harrison Ifeanyichukwu
committed
docs: Update Readme guide, add usage guide
1 parent 8b10eea commit 331f77b

File tree

2 files changed

+237
-18
lines changed

2 files changed

+237
-18
lines changed

‎README.md‎

Lines changed: 229 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,30 +1,246 @@
1-
# W3C-XML-Serializer
1+
# XML-Serializer
22

3-
[![Build Status](https://travis-ci.org/harrison-ifeanyichukwu/w3c-xml-serializer.svg?branch=master)](https://travis-ci.org/harrison-ifeanyichukwu/w3c-xml-serializer)
4-
[![Coverage Status](https://coveralls.io/repos/github/harrison-ifeanyichukwu/w3c-xml-serializer/badge.svg?branch=master)](https://coveralls.io/github/harrison-ifeanyichukwu/w3c-xml-serializer?branch=master)
3+
[![Build Status](https://travis-ci.org/harrison-ifeanyichukwu/xml-serializer.svg?branch=master)](https://travis-ci.org/harrison-ifeanyichukwu/xml-serializer)
4+
[![Coverage Status](https://coveralls.io/repos/github/harrison-ifeanyichukwu/xml-serializer/badge.svg?branch=master)](https://coveralls.io/github/harrison-ifeanyichukwu/xml-serializer?branch=master)
55
[![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release)
66

7-
`W3C-XML-Serializer` is A JavaScript implementation of w3c [xml serialization](https://www.w3.org/TR/DOM-Parsing/#dfn-concept-serialize-xml) spec. All specifications have been implemented and includes the following [specs](https://www.w3.org/TR/DOM-Parsing/#dfn-concept-xml-serialization-algorithm):
7+
XML-Serializer is A JavaScript complete implementation of the W3C [xml serialization](https://www.w3.org/TR/DOM-Parsing/#dfn-concept-serialize-xml) spec. All specifications have been implemented and includes the following [specs](https://www.w3.org/TR/DOM-Parsing/#dfn-concept-xml-serialization-algorithm):
88

9-
- [Element node Serialization]
9+
- [ELEMENT_NODE Serialization]
1010

11-
- [Document node Serialization]
11+
- [DOCUMENT_NODE Serialization]
1212

13-
- [Comment node Serialization]
13+
- [COMMENT_NODE Serialization]
1414

15-
- [Text node Serialization]
15+
- [TEXT_NODE Serialization]
1616

17-
- [Document Fragment node Serialization]
17+
- [DOCUMENT_FRAGMENT_NODE Serialization]
1818

19-
- [Document Type Serialization]
19+
- [DOCUMENT_TYPE_NODE Serialization]
2020

21-
- [Processing Instruction Serialization]
21+
- [PROCESSING_INSTRUCTION_NODE Serialization]
2222

2323
## Module Availability
2424

25-
This module is available as an npm package and also as a browser module. It can easily integrated with [JSDOM](https://github.com/jsdom/jsdom) for mockup testing.
25+
This module is available as an [npm](https://www.npmjs.com/) scoped package and also has a browser build that is located inside the `dist` folder. It can easily be integrated with [JSDOM](https://github.com/jsdom/jsdom) for mockup testing.
2626

27-
## Useful Articles
27+
## Installing the Package
28+
29+
The below command will install `xml-serializer` from npm into your project assuming you have the [npm](https://www.npmjs.com/) already installed.
30+
31+
> NB: Because of some conflicting package names that already exists on npm, this one has been turned into a scoped package with public access.
32+
33+
**Install as a development dependency**:
34+
35+
```bash
36+
npm install --save-dev @harrison-ifeanyichukwu/xml-serializer
37+
```
38+
39+
**Install as a production dependency**:
40+
41+
```bash
42+
npm install --save @harrison-ifeanyichukwu/xml-serializer
43+
```
44+
45+
## Usage Guide
46+
47+
following the specification, the `XMLSerializer` interface is a constructor and has a `serializeToString(root)` method exposed on the instance. To serialize any xml node, call the `serializeToString(root)` method on a constructed instance, passing in the xml node as below
48+
49+
```javascript
50+
import XMLSerializer from '@harrison-ifeanyichukwu/xml-serializer';
51+
52+
let instance = new XMLSerializer();
53+
console.log(instance.serializeToString(someXmlNode));
54+
```
55+
56+
### Using with [JSDOM](https://github.com/jsdom/jsdom)
57+
58+
Currently, JSDOM has not implemented the `XMLSerializer` feature. This can be easily integrated with JSDOM and any other similar mockup environment like below.
59+
60+
```javascript
61+
//assumes jsdom has been installed.
62+
import XMLSerializer from '@harrison-ifeanyichukwu/xml-serializer';
63+
import {JSDOM} from 'jsdom';
64+
65+
let dom = new JSDOM();
66+
67+
dom.window.XMLSerializer = XMLSerializer;
68+
69+
global.window = dom.window;
70+
71+
//start running your tests or do something else.
72+
```
73+
74+
### Using on the browser
75+
76+
The browser build is available inside the dist folder. It exposes the `XMLSerialzer` construct on the `window` object.
77+
78+
## New Features & Improvements
79+
80+
By default, the serializer preserves white space during the serialization process. This can be turned off by passing in false to the constructor at the time of creating an instance.
81+
82+
```javascript
83+
let instance = new XMLSerializer(false) // preserveWhiteSpace is set to false. it wont
84+
//preserve white spaces
85+
```
86+
87+
Another improvement is that it removes all duplicate prefix definition on any xml element which is part of the specification unlike what web browsers do. Below is an example of this
88+
89+
**Original XML**:
90+
91+
```xml
92+
<?xml version="1.0" encoding="utf-8" ?>
93+
<!DOCTYPE root PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
94+
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
95+
96+
<?xml-stylesheet href="classic.css" alternate="yes" title="Classic"
97+
media="screen, print" type="text/css"?>
98+
99+
<!--notice that two namespaces have been defined on the root element-->
100+
<root xmlns:h="http://www.w3.org/TR/html4/" xmlns:f="https://www.w3schools.com/furniture">
101+
102+
<!--notice that it is declared again here. this is a duplicate-->
103+
<h:table xmlns:h="http://www.w3.org/TR/html4/" xmlns:f="https://www.w3schools.com/furniture">
104+
<h:tr>
105+
<h:td>
106+
<h:td>Apples</h:td>
107+
<h:td>Bananas</h:td>
108+
</h:tr>
109+
</h:table>
110+
111+
<!--one is duplicated here-->
112+
<f:table xmlns:f="https://www.w3schools.com/furniture">
113+
<f:name>African Coffee Table</f:name>
114+
<f:width>80</f:width>
115+
<f:length>120</f:length>
116+
</f:table>
117+
118+
<!--html section-->
119+
<html xmlns="http://www.w3.org/1999/xhtml">
120+
<head>
121+
<meta name="description" content="this is html section" />
122+
<base href="http://localhost" />
123+
</head>
124+
<body>
125+
<p>this is a paragraph text</p>
126+
<hr />
127+
<template>
128+
<p>this is a template</p>
129+
</template>
130+
</body>
131+
</html>
132+
133+
<svg:svg xmlns:svg="http://www.w3.org/2000/svg">
134+
<svg:style></svg:style>
135+
<title>my title<title>
136+
</svg:svg>
137+
138+
</root>
139+
```
140+
141+
**Chrome inbuilt XMLSerializer Output:**
142+
143+
```xml
144+
<?xml version="1.0" encoding="utf-8" ?><!DOCTYPE root PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
145+
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
146+
147+
<?xml-stylesheet href="classic.css" alternate="yes" title="Classic"
148+
media="screen, print" type="text/css"?>
149+
150+
<!--notice that two namespaces have been defined on the root element-->
151+
<root xmlns:h="http://www.w3.org/TR/html4/" xmlns:f="https://www.w3schools.com/furniture">
152+
153+
<!--notice that it is declared again here. this is a duplicate-->
154+
<h:table xmlns:h="http://www.w3.org/TR/html4/" xmlns:f="https://www.w3schools.com/furniture">
155+
<h:tr>
156+
<h:td>
157+
<h:td>Apples</h:td>
158+
<h:td>Bananas</h:td>
159+
</h:tr>
160+
</h:table>
161+
162+
<!--one is duplicated here-->
163+
<f:table xmlns:f="https://www.w3schools.com/furniture">
164+
<f:name>African Coffee Table</f:name>
165+
<f:width>80</f:width>
166+
<f:length>120</f:length>
167+
</f:table>
168+
169+
<!--html section-->
170+
<html xmlns="http://www.w3.org/1999/xhtml">
171+
<head>
172+
<meta name="description" content="this is html section" />
173+
<base href="http://localhost" />
174+
</head>
175+
<body>
176+
<p>this is a paragraph text</p>
177+
<hr />
178+
<template>
179+
<p>this is a template</p>
180+
</template>
181+
</body>
182+
</html>
183+
184+
<svg:svg xmlns:svg="http://www.w3.org/2000/svg">
185+
<svg:style></svg:style>
186+
<title>my title<title>
187+
</svg:svg>
188+
189+
</root>
190+
```
191+
192+
**Output of this module: removes the duplicate namspace declarations:**
193+
194+
```xml
195+
<?xml version="1.0" encoding="utf-8" ?><!DOCTYPE root PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
196+
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
197+
198+
<?xml-stylesheet href="classic.css" alternate="yes" title="Classic"
199+
media="screen, print" type="text/css"?>
200+
201+
<!--notice that two namespaces have been defined on the root element-->
202+
<root xmlns:h="http://www.w3.org/TR/html4/" xmlns:f="https://www.w3schools.com/furniture">
203+
204+
<!--notice that it is declared again here. this is a duplicate-->
205+
<h:table>
206+
<h:tr>
207+
<h:td>
208+
<h:td>Apples</h:td>
209+
<h:td>Bananas</h:td>
210+
</h:tr>
211+
</h:table>
212+
213+
<!--one is duplicated here-->
214+
<f:table>
215+
<f:name>African Coffee Table</f:name>
216+
<f:width>80</f:width>
217+
<f:length>120</f:length>
218+
</f:table>
219+
220+
<!--html section-->
221+
<html xmlns="http://www.w3.org/1999/xhtml">
222+
<head>
223+
<meta name="description" content="this is html section" />
224+
<base href="http://localhost" />
225+
</head>
226+
<body>
227+
<p>this is a paragraph text</p>
228+
<hr />
229+
<template>
230+
<p>this is a template</p>
231+
</template>
232+
</body>
233+
</html>
234+
235+
<svg:svg xmlns:svg="http://www.w3.org/2000/svg">
236+
<svg:style></svg:style>
237+
<title>my title<title>
238+
</svg:svg>
239+
240+
</root>
241+
```
242+
243+
## Acknowledgments
28244

29245
In addition to the spec, the following sections as well as outside resources were consulted and proved very useful:
30246

‎package.json‎

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2,13 +2,16 @@
22
"name": "@harrison-ifeanyichukwu/xml-serializer",
33
"version": "0.0.0-development",
44
"description": "A javascript implementation of w3c xml-serialization spec",
5-
"main": "main.js",
5+
"main": "lib/main.js",
6+
"publishConfig": {
7+
"access": "public"
8+
},
69
"scripts": {
710
"commit": "git-cz",
811
"test": "BABEL_ENV=test nyc mocha --recursive",
912
"test-watch": "BABEL_ENV=test nyc mocha --recursive -w",
1013
"report-coverage": "nyc report --reporter=text-lcov | coveralls",
11-
"prebuild": "rimraf dist",
14+
"prebuild": "rimraf dist && rimraf lib",
1215
"build": "BABEL_ENV=build rollup --config",
1316
"travis-deploy-once": "travis-deploy-once",
1417
"semantic-release": "semantic-release",
@@ -17,7 +20,7 @@
1720
},
1821
"repository": {
1922
"type": "git",
20-
"url": "https://github.com/harrison-ifeanyichukwu/w3c-xml-serializer.git"
23+
"url": "https://github.com/harrison-ifeanyichukwu/xml-serializer.git"
2124
},
2225
"keywords": [
2326
"xml-serialization",
@@ -29,9 +32,9 @@
2932
"author": "Harrison Ifeanyichukwu <Harrisonifeanyichukwu@gmail.com> (https://harrison-ifeanyichukwu.github.io/)",
3033
"license": "MIT",
3134
"bugs": {
32-
"url": "https://github.com/harrison-ifeanyichukwu/w3c-xml-serializer/issues"
35+
"url": "https://github.com/harrison-ifeanyichukwu/xml-serializer/issues"
3336
},
34-
"homepage": "https://github.com/harrison-ifeanyichukwu/w3c-xml-serializer#readme",
37+
"homepage": "https://github.com/harrison-ifeanyichukwu/xml-serializer#readme",
3538
"devDependencies": {
3639
"babel-plugin-external-helpers": "6.22.0",
3740
"babel-preset-env": "1.7.0",

0 commit comments

Comments
 (0)