bbfy BBCode Processor
bbfy is a modular, extensible BBCode parser and converter for node.js/io.js and web browsers.
Installation
For use with node.js or io.js, bbfy can be installed through npm:
npm install bbfy
bbfy can also be run inside web browsers, by using bbfy.browser.js. Since it
supports UMD, it can be integrated standalone or through an AMD loader such
as RequireJS. Rename bbfy.browser.js to bbfy.js and copy it to your project.
For standalone use, reference it through a source
tag:
<script src="bbfy.js"></script>
AMD loaders can simply list and use bbfy
as a require
or define
dependency:
Copying bbfy.browser.js.map is optional and provides debugging capabilities as bbfy.browser.js is uglified.
Usage
bbfy exposes one function, converter
, which optionally takes an object of
options. Invoking converter
returns and anonymous function that converts
BBCode-enriched text based on the provided ruleset.
var convert = bbfy;var bbcode = '[b]Hello World![/b]';var html = ; // <b>Hello World!</b>
The default ruleset converts BBCode to standards-compliant HTML.
All defaults are exposed via bbfy.options
and pre-defined rulesets as
bbfy.ruleSets
. The call to converter
supports overriding the ruleset by
setting the key rules
. Additionally, the key unsupported
can be assigned to
a fallback function handling unknown BBCode tags. The default one just strips
off the tags.
The internal API is exposed through bbfy.api
and should only be used at your
own discretion as there a no guarantees towards stability or consistency
throughout releases.
API
- bbfy.converter({ rules, unsupported, lineTags } (optional)) => fn (string) => string
- BBCode to anything converter. `rules` has to be an object mapping tag names to functions of the form `fn (text, tag, args) => string`. The input string is the text inside the bbcode tags. `tag` is the name of the tag itself. The format of `args` depends on the kind of assignment present, if any, and can be a simple string or an object. The converter may through an error message if there is a fatal error during parsing th input string, but this is unlikely to ever happen. `unsupported` get called for properly parsed tags that don't match any rule in the ruleset and takes the same options as the other rules. `lineTags` is an array of BBCode tags to be terminated by newlines.
- bbfy.options
- Contains the defaults for rulesets, unsupported tags and line tags. Here it is possible to override them on a global scale.
- bbfy.ruleSets
- A mapping of predefined rulesets. By default, only `strip` and `html`. `strip` removes all BBCode tags, which is useful e.g. for web standard notifications.
- bbfy.api
- Exposes all internal functions, mainly for unit testing purposes. As there are no guarantees for the API, please see the source code itself if you want to use it anyway.
Development
bbfy is written in ES6 and built using gulp. Run npm install
to fetch all
dependencies needed for building bbfy and gulp compile
to build the node.js
version in target/bbfy.js
. gulp bundle
builds the browser version bundling
all dependencies using browserify. The output file is target/bbfy.browser.js
.
gulp test
runs all tests and gulp watch
watches for source code or test code
changes and re-runs all building and test tasks on demand.
If you don't want to install gulp globally, you can run it off the local node
depedency cache: node_modules/gulp/bin/gulp.js
.
Supported HTML Tags
At this point, bbfy supports conversion of the following tags:
BBCode | HTML | Description | Supported Attributes |
---|---|---|---|
b | b | Emphasis | |
i | i | Italic | |
u | u | Underline | |
s | s | Striketrough | |
color | span color | Font color | |
font | span font-family | Font family | |
size | span font-size | Font size | |
url | a href | Hyperlink | |
img | img | Image | width, height |
Links
License
Copyright © 2015 LShift Services GmbH
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.