mirror of
https://github.com/marko-js/marko.git
synced 2025-12-08 19:26:05 +00:00
Trimmed down README.md for Marko v4
This commit is contained in:
Patrick Steele-Idem
parent
d4404f6240
commit
431753f0e8
270
README.md
270
README.md
@ -2,9 +2,8 @@
|
||||
<a href="http://markojs.com/"><img src="https://raw.githubusercontent.com/marko-js/branding/master/marko-logo-medium-cropped.png" alt="Marko logo" width="300" /></a><br /><br />
|
||||
</p>
|
||||
|
||||
Marko is a [_really_ fast](https://github.com/marko-js/templating-benchmarks) and lightweight UI component building library from eBay. Marko runs on Node.js and in the browser and it supports streaming, async rendering and custom tags. UI components compiled to readable CommonJS modules. Learn more on [markojs.com](http://markojs.com/), and even [Try Marko Online!](http://markojs.com/try-online/)
|
||||
|
||||
> :rocket: The upcoming Marko v4 release with a lot of exciting improvements is almost ready! Please see the [ROADMAP](./ROADMAP.md) to find out what's changing.
|
||||
Marko a friendly (and fast!) UI library that makes building web apps fun.
|
||||
Learn more on [markojs.com](http://markojs.com/), and even [Try Marko Online!](http://markojs.com/try-online/)
|
||||
|
||||
[](https://travis-ci.org/marko-js/marko)
|
||||
[](https://coveralls.io/github/marko-js/marko?branch=master)
|
||||
@ -27,268 +26,6 @@ Marko is a [_really_ fast](https://github.com/marko-js/templating-benchmarks) an
|
||||
npm install marko --save
|
||||
```
|
||||
|
||||
# Syntax
|
||||
|
||||
Marko supports _both_ a familiar HTML syntax, as well as a more concise indentation-based syntax. Both syntaxes are equally supported. Regardless of which syntax you choose, the compiled code will be exactly the same.
|
||||
|
||||
## HTML syntax
|
||||
|
||||
```html
|
||||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<title>Marko Templating Engine</title>
|
||||
</head>
|
||||
<body>
|
||||
<h1>
|
||||
Hello ${data.name}!
|
||||
</h1>
|
||||
|
||||
<if(data.colors.length)>
|
||||
<ul>
|
||||
<for(color in data.colors)>
|
||||
<li>
|
||||
${color}
|
||||
</li>
|
||||
</for>
|
||||
</ul>
|
||||
</if>
|
||||
<else>
|
||||
<div>
|
||||
No colors!
|
||||
</div>
|
||||
</else>
|
||||
</body>
|
||||
</html>
|
||||
```
|
||||
|
||||
Alternatively, you can choose to apply rendering logic as "attributes":
|
||||
|
||||
```html
|
||||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<title>Marko Templating Engine</title>
|
||||
</head>
|
||||
<body>
|
||||
<h1>
|
||||
Hello ${data.name}!
|
||||
</h1>
|
||||
|
||||
<ul if(data.colors.length)>
|
||||
<li for(color in data.colors)>
|
||||
${color}
|
||||
</li>
|
||||
</ul>
|
||||
<div else>
|
||||
No colors!
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
```
|
||||
|
||||
## Concise syntax
|
||||
|
||||
The following concise template is equivalent to the previous template:
|
||||
|
||||
```html
|
||||
<!DOCTYPE html>
|
||||
html lang="en"
|
||||
head
|
||||
title - Marko Templating Engine
|
||||
body
|
||||
h1 - Hello ${data.name}!
|
||||
ul if(data.colors.length)
|
||||
li for(color in data.colors)
|
||||
${color}
|
||||
div else
|
||||
- No colors!
|
||||
```
|
||||
|
||||
Alternatively, you can choose to apply rendering logic as separate "tags":
|
||||
|
||||
```html
|
||||
<!DOCTYPE html>
|
||||
html lang="en"
|
||||
head
|
||||
title - Marko Templating Engine
|
||||
body
|
||||
h1 - Hello ${data.name}!
|
||||
if(data.colors.length)
|
||||
ul
|
||||
for(color in data.colors)
|
||||
li - ${color}
|
||||
else
|
||||
div - No colors!
|
||||
```
|
||||
|
||||
## Mixed syntax
|
||||
|
||||
You can even mix and match the concise syntax with the HTML syntax within the same document.
|
||||
The following template is equivalent to the previous templates:
|
||||
|
||||
```html
|
||||
<!DOCTYPE html>
|
||||
html lang="en"
|
||||
head
|
||||
title - Marko Templating Engine
|
||||
body
|
||||
<h1>
|
||||
Hello ${data.name}!
|
||||
</h1>
|
||||
ul if(data.colors.length)
|
||||
li for(color in data.colors)
|
||||
${color}
|
||||
div else
|
||||
- No colors!
|
||||
```
|
||||
|
||||
# Basic Usage
|
||||
|
||||
## Loading a template
|
||||
|
||||
```javascript
|
||||
var template = require('./template.marko');
|
||||
```
|
||||
|
||||
NOTE: On the server, you will need to install the Node.js require extension for Marko:
|
||||
|
||||
```javascript
|
||||
require('marko/node-require').install();
|
||||
```
|
||||
|
||||
## Rendering a template
|
||||
|
||||
```javascript
|
||||
var templateData = { name: 'Frank' };
|
||||
|
||||
// Render to an existing Writable stream:
|
||||
template.render(templateData, process.stdout);
|
||||
|
||||
// Render to a callback function:
|
||||
template.render(templateData, function(err, html) {
|
||||
console.log(html);
|
||||
});
|
||||
|
||||
// Render a template synchronously
|
||||
console.log(template.renderSync(templateData));
|
||||
|
||||
// Render a template and return a new Readable stream:
|
||||
template.stream(templateData).pipe(process.stdout);
|
||||
```
|
||||
|
||||
# UI Components
|
||||
|
||||
Marko Components is a minimalist library for building isomorphic/universal UI components with the help of the
|
||||
[Marko templating engine](http://markojs.com/docs/). Marko renders the HTML for UI components, while Marko Components adds client-side behavior. Client-side behavior includes the following:
|
||||
|
||||
- Handling DOM events
|
||||
- Emitting custom events
|
||||
- Handling custom events emitted by other components
|
||||
- Manipulating and updating the DOM
|
||||
|
||||
Marko Components offers advanced features like DOM-diffing, batched updates, stateful components, declarative event binding and efficient event delegation.
|
||||
|
||||
Changing a components state or properties will result in the DOM automatically being updated without writing extra code. Marko Components has adopted many of the good design principles promoted by the [React](https://facebook.github.io/react/index.html) team, but aims to be much lighter and often faster (especially on the server). When updating the view for a component, Marko Components uses DOM diffing to make the minimum number of changes to the DOM through the use of the [morphdom](https://github.com/patrick-steele-idem/morphdom) module.
|
||||
|
||||
UI components are defined using very clean JavaScript code. For example:
|
||||
|
||||
```javascript
|
||||
module.exports = require('marko-components').defineComponent({
|
||||
/**
|
||||
* The template to use as the view
|
||||
*/
|
||||
template: require('./template.marko'),
|
||||
|
||||
/**
|
||||
* Return the initial state for the UI component based on
|
||||
* the input properties that were provided.
|
||||
*/
|
||||
getInitialState: function(input) {
|
||||
return {
|
||||
greetingName: input.greetingName,
|
||||
clickCount: 0
|
||||
};
|
||||
},
|
||||
|
||||
/**
|
||||
* Return an object that is used as the template data. The
|
||||
* template data should be based on the current component state
|
||||
* that is passed in as the first argument
|
||||
*/
|
||||
getTemplateData: function(state) {
|
||||
var clickCount = state.clickCount;
|
||||
var timesMessage = clickCount === 1 ? 'time' : 'times';
|
||||
|
||||
return {
|
||||
greetingName: state.greetingName,
|
||||
clickCount: clickCount,
|
||||
timesMessage: timesMessage
|
||||
};
|
||||
},
|
||||
|
||||
/**
|
||||
* This is the constructor for the component. Called once when
|
||||
* the component is first added to the DOM.
|
||||
*/
|
||||
init: function() {
|
||||
var el = this.el;
|
||||
// "el" will be reference the raw HTML element that this
|
||||
// component is bound to. You can do whatever you want with it...
|
||||
// el.style.color = 'red';
|
||||
},
|
||||
|
||||
/**
|
||||
* Handler method for the button "click" event. This method name
|
||||
* matches the name of the `w-onClick` attribute in the template.
|
||||
*/
|
||||
handleButtonClick: function(event, el) {
|
||||
this.setState('clickCount', this.state.clickCount + 1);
|
||||
},
|
||||
|
||||
/**
|
||||
* Expose a method to let other code change the "greeting name".
|
||||
* If the value of the "greetingName" state property changes
|
||||
* then the UI component will automatically rerender and the
|
||||
* DOM will be updated.
|
||||
*/
|
||||
setGreetingName: function(newName) {
|
||||
this.setState('greetingName', newName);
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
And, here is the corresponding Marko template for the UI component:
|
||||
|
||||
```xml
|
||||
<div class="click-count">
|
||||
Hello ${data.greetingName}!
|
||||
<div>
|
||||
You clicked the button ${data.clickCount} ${data.timesMessage}.
|
||||
</div>
|
||||
<button type="button" onClick("handleButtonClick")>
|
||||
Click Me
|
||||
</button>
|
||||
</div>
|
||||
```
|
||||
|
||||
<a href="http://markojs.com/marko-components/try-online/" target="_blank">Try Marko Components Online!</a>
|
||||
|
||||
For more details on Marko Components, please check out the [Marko Components Documentation](http://markojs.com/docs/marko-components/).
|
||||
|
||||
# Common issues
|
||||
|
||||
## nodemon
|
||||
|
||||
When `marko` compiles your server-side templates, a `.marko.js` file is created next to the original `.marko` file.
|
||||
Subsequently, `nodemon` will see the new `.marko.js` file and trigger a restart of your app and this can
|
||||
repeat indefinitely unless you configure `nodemon` to ignore `*.marko.js` files.
|
||||
To avoid this, simply add `"ignore": ["*.marko.js"]` to the `nodemon.json` file at the root of your project.
|
||||
|
||||
As a better drop-in replacement with more features, you can install [browser-refresh](https://github.com/patrick-steele-idem/browser-refresh).
|
||||
Be sure to add `*.marko.js` pattern to your `.gitignore` file and `browser-refresh`
|
||||
will automatically ignore the compiled marko templates when they are written to disk.
|
||||
|
||||
# Changelog
|
||||
|
||||
See [CHANGELOG.md](CHANGELOG.md)
|
||||
@ -296,8 +33,9 @@ See [CHANGELOG.md](CHANGELOG.md)
|
||||
# Maintainers
|
||||
|
||||
* [Patrick Steele-Idem](https://github.com/patrick-steele-idem) (Twitter: [@psteeleidem](http://twitter.com/psteeleidem))
|
||||
* [Phillip Gates-Idem](https://github.com/philidem/) (Twitter: [@philidem](https://twitter.com/philidem))
|
||||
* [Michael Rawlings](https://github.com/mlrawlings) (Twitter: [@mlrawlings](https://twitter.com/mlrawlings))
|
||||
* [Phillip Gates-Idem](https://github.com/philidem/) (Twitter: [@philidem](https://twitter.com/philidem))
|
||||
* [Austin Kelleher](https://github.com/austinkelleher) (Twitter: [@AustinKelleher](https://twitter.com/AustinKelleher))
|
||||
* [Martin Aberer](https://github.com/tindli) (Twitter: [@metaCoffee](https://twitter.com/metaCoffee))
|
||||
|
||||
# License
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user