html-extend
Issue
For example, you have some html file with <table>
tag with rich markup and you need it in another file but without some buttons, different classes and labels, or even worse, you will need to wrap some tag. You can solve it with dozens of parameters and if's but you markup will become unreadable.
My solution
Extend origin html file using es6 like module system and annotations.
Install
npm install html-extend
Contents
- API
- Annotations
- export
- global
- import
- Tags
- Attributes
- Text
- Annotations
- Contribute
API
/** * @param * @returns */
/** * @param * @returns */
{HtmlModule}
is dom object of simple-html-dom-parser with imports
and exports
properties
/** * @param * @param * @returns */
/** * @param * @returns */
/** * @property */globalTags
It's hash where keys are names of global tags and values should be DomObject
or html string or function (which will take DomObject
and should return string or new DomObject
).
/** * @param * @param */
handler
will take file path and should return hash with exported tag names, which values should be DomObject
or html string or function (which will take DomObject
and should return string or new DomObject
).
Example
component.xhtml
{label}
var setExtension = setExtension; ;
import Component from './component'
Some Title
With setExtension
you can even rewrite default html
extension handler.
To remove extension just set null
;
Annotations
Annotations is text or comment like @annotationName
before tags which describes how tag should be modified.
@export
Annotation which used to export tags. The only option is the name of exported tag. It's same as in CommonJS when you write exports.TagName
or in es6 export TagName
will be @export TagName
. Also as in es6 export default
you can write @export default
or just @export
and this tag will be default for current module. You can export any tag from file, not just root tags. You can use dots and dashes in tag name. You can use as many export names as you wish.
@export default@export Layout @export ButtonXS OK <!-- @export Button.SM --> OK <!-- | @export btn-lg | @export Btn.lg | @export Bootstrap.btn-lg +--> OK
@global
This annotation same as @export
only it will export to global scope
import
import
is a keyword, not annotation, because it's not binded to any tag, it should be only on top of file or after <!DOCTYPE ...>
. Syntax is same as for es6.
Then you can use those tags.
As you can see you can share your html modules through npm and import
will find it just like native require()
.
Path to tag
You have two options to point on tag which you want to modify.
First is write same tags tree to tag.
@export Item Title 1 Title 2 Title 3
import {Item} from './module1' @prepend Title @append OK
=
Title Title OK
If you don't want or don't know tags names, simply write <tag>
...
To point to third tag
...
Second is to use @find
Add tag
If in parent tag only one child and you write two then second will be added.
@export Item
import {Item} from './module1'
=
Also annotations like @prepend
and @append
can add tags.
Remove tag
See @remove
Rename tag
Just point to needed tag and write new name
@export Item
import {Item} from './module1'
=
Add/rewrite attribute
Any attribute (except class
) will be rewrited if it not exist in parent, it will be added.
@export Item Title
import {Item} from './module1'
=
Title
Remove attribute
To remove attribute just write !
before it
@export Item Title
import {Item} from './module1'
=
Title
Shadow attribute
When attribute name starts with ~
it means it's shadow attribute and it needed only to pass some value to extended module. This type of attribute will not add, remove or rewrite parent attribute. See example of setExtension function.
Add class
All class names will be added (not rewrited) to parent tag.
@export Item Title
import {Item} from './module1'
=
Title
Remove class
To remove class name write !
before it
@export Item Title
import {Item} from './module1'
=
Title
Rewrite text in tag
Any text will rewrite parent text.
@export Item Title Title
import {Item} from './module1' Main title Sub title Title Title Title
=
Main title Sub title Title Title Title
Remove text
To remove text you need write some html entity like
or if you no need space then ​
or similar.
@find
With this annotation you can point to tag with css selector.
@export Item Title Description
import {Item} from './module1' @find .header @append Sub title @append Text
=
Title Sub title Description Text
@append
It will add tag to the end of current tag parent.
@export Item Title
import {Item} from './module1' @append OK Title
=
TitleOK
If you want to add several tags then you need to write @append
before each of them.
@prepend
Will add tag on first place of current parent
@export Item Title
import {Item} from './module1' @prepend OK
=
OK Title
@insert
Will add tag on current place.
@export Item Title Description Ok
import {Item} from 'module1' @insert
=
Title Description Ok
@remove
Will remove current tag
@export Item OK
import {Item} from './module1' @remove
=
OK
@empty
Will remove children of current tag.
@export Item Description OK
import {Item} from './module1' @empty Title
=
Title
@appendTo
Will add tag to another tag by css selector.
@export Item Description
import {Item} from './module1' @appendTo .description Read more
=
DescriptionRead more
@prependTo
Will add tag to the beginig of another tag by css selector
@export Item Description
import {Item} from './module1' @prependTo .content Title
=
Title Description
@insertBefore
Will add tag before another tag by css selector
@export Item Title Description
import {Item} from './module1' @insertBefore .description Sub title
=
Title Sub titleDescription
@insertAfter
Will add tag after another tag by css selector
@export Item Title Description
import {Item} from './module1' @insertAfter .content h1 Sub title
=
TitleSub title Description
Contribute
Help me improve this doc and any comments are welcome in issues.