From fbd938cb7b872cbc5ed7c1b3066cbb2f9d9a0f4f Mon Sep 17 00:00:00 2001 From: Google Code Exporter Date: Sun, 16 Aug 2015 06:23:40 -0400 Subject: [PATCH] Migrating wiki contents from Google Code --- ProjectHome.md | 64 +++++++++++++++++++ Templates.md | 55 ++++++++++++++++ Testing.md | 22 +++++++ ViewHelpers.md | 170 +++++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 311 insertions(+) create mode 100644 ProjectHome.md create mode 100644 Templates.md create mode 100644 Testing.md create mode 100644 ViewHelpers.md diff --git a/ProjectHome.md b/ProjectHome.md new file mode 100644 index 0000000..1a45048 --- /dev/null +++ b/ProjectHome.md @@ -0,0 +1,64 @@ +EJS cleans the HTML out of your JavaScript with client side templates. After EJS gets its rubber gloves on dirty code, you'll feel organized and uncluttered. + +| [Home](http://embeddedjs.com/) | [Getting Started Guide](http://embeddedjs.com/getting_started.html) | [NBA Demo ](http://embeddedjs.com/application.html) | [How-to Screencast ](http://embeddedjs.com/screencast/index.html) | +|:--------------------------------|:--------------------------------------------------------------------|:----------------------------------------------------|:------------------------------------------------------------------| + +# Description # + +EJS is essentially a port of Masatoshi Seki's erb.rb in the Ruby Core. It operates in the same way that PHP, ERB, or any of the other embedded language interpreters work, except where all existing preprocessing engines execute on the server-side, EJS is intended to run within the web browser. This allows client-side code to process JavaScript-based web templates for insertion into the current page without consulting the server. + +EJS uses <% %> or [% %] as its magic tags. Like most other frameworks of its type, <% %> tags cause all code within them to be executed, and the addition of an equals sign (<%= %>) causes the enclosed code to be evaluated and the toString representation of the result appended to the document. + + +## Typical Use ## +EJS templates can be loaded within a page or a separate file. Once the EJS template is loaded, it is passed data used to render template. The result of the render is typically used to update HTML on the page. + +### Example ### +With this example, we will create and load a template that displays a list of cleaning supplies. + +First, lets create a template file that iterates through a list of supplies: +``` + + +

Supplies

+ +``` + +Next, we create an object to hold those supplies: +``` +var my_supplies = {supplies: ['mop', 'broom', 'duster']} +``` + +Finally, we load the template, render it with the supply object, and update an HTML element with the results. + +``` +var result = new EJS({url: 'templates/supplies.ejs'}).render(my_supplies); +document.getElementById('supply_list').innerHTML = result +``` + + + +# View Helpers # +EJS includes view helpers to make building repetitive HTML snippets easier. The view helpers are very similar to Ruby on Rails ActionView helpers. + +## Example ## +The following builds a form that adds cleaning supplies. +``` +<%= form_tag('/cleaning/add_supply') %> + <%= input_field_tag('cleaning_supply') %> + <%= submit_tag('Submit') %> +<%= form_tag_end() %> +``` + + +# Error Handling # +Using a special version of JSLint, EJS can provide nice error handling when you are developing your templates. +By including ejs\_fulljslint similar to +``` + +``` +EJS will error with a line number if there is a syntax error. \ No newline at end of file diff --git a/Templates.md b/Templates.md new file mode 100644 index 0000000..bb94c82 --- /dev/null +++ b/Templates.md @@ -0,0 +1,55 @@ +# Introduction # + +EJS provides a lot of flexibility for using JavaScript templates. This article documents EJS's template API. + +EJS is typically used by loading a template and rendering it with data. + +# Loading a template # + +Load a template by creating a new EJS template. Templates are cached by default. + +### Example ### +``` +template = new EJS({url: '/mytemplate.ejs'}) +``` +options is a hash that can include the following attributes: + + * url {string} - loads a template from a file + * text {string} - uses the provided text as the template + * element {string or element} - loads a template from the innerHTML or value of the element. + type {string} (optional) - '<' or '[', default is '<', except for loading a template from an element. + * name {string} (optional) - an optional name that is used for caching. This defaults to the element ID or URL provided. + * cache {boolean} (optional) - defaults to true. True if you want to enable caching of templates, false if otherwise. + + +# Rendering # + +There are 2 ways to render a template. The first method, render, simply returns text. Other method, update, is used to update the inner HTML of an element. + +## render(data) ## +Renders the template with the provided data. +``` + html = new EJS({url: '/template.ejs'}).render(data) +``` + +## update(element, url\_or\_data) ## +Updates an element with the result of the template. + +### options ### +**element** {string or element} - the element you want updated + +**url\_or\_data** - can be one of the following: +> {null} - returns a function that takes an object as its first argument. That object will be used to render the template and update the element. + +> {string} - The string is used as a url to perform an AJAX request. The data returned from the ajax request is used to render the template and update the element. + +> {object} - Data used to render the template and update the element. + +### Examples ### +``` +f = new EJS({url: '/mytemplate.ejs'}).update('my_element') + +new EJS({url: '/mytemplate.ejs'}).update('my_element', '/data.json') + +new EJS({url: '/mytemplate.ejs'}).update('my_element', {supplies: ['mop']}) +``` \ No newline at end of file diff --git a/Testing.md b/Testing.md new file mode 100644 index 0000000..1913312 --- /dev/null +++ b/Testing.md @@ -0,0 +1,22 @@ +# Introduction # + +EJS uses scriptaculous's testing functionality. + + +# Instructions # + +After obtaining the trunk folder from SVN: + 1. open test/index.html + 1. On the left frame, click 'Rendering Test' or 'Templating Test' to test ejs or templates respectively. + +# Tests # + +## Rendering Test ## + +### render with left bracket ### + +Tests with the default delimiters [% %] + +### render with left carrot ### + +Tests with erb-style delimiters <% %> \ No newline at end of file diff --git a/ViewHelpers.md b/ViewHelpers.md new file mode 100644 index 0000000..fdcfc07 --- /dev/null +++ b/ViewHelpers.md @@ -0,0 +1,170 @@ +# Introduction # + +EJS provides view helpers for common tasks. These helpers are very similar to those found in the Ruby On Rails framework. + +| date\_tag | form\_tag | form\_tag\_end | hidden\_field\_tag | input\_field\_tag | +|:----------|:----------|:---------------|:-------------------|:------------------| +| is\_current\_page | link\_to | submit\_link\_to | link\_to\_if | link\_to\_unless | +| link\_to\_unless\_current | password\_field\_tag | select\_tag | single\_tag\_for | start\_tag\_for | +| submit\_tag | tag | tag\_end | text\_area\_tag | text\_tag | +| text\_field\_tag | url\_for | img\_tag | + +# Details # + +### date\_tag(name, value, html\_options) ### +Creates a date tag +``` +date_tag('Installation[date]', new Date(1982, 10,20) ) +``` + + +### form\_tag(action, html\_options) ### +Creates a start form tag. +``` +form_tag('/myaction',{multipart: true}) +``` + + +### end\_form\_tag() ### +Creates a start form tag. +``` +form_tag_end() +``` + + +### hidden\_field\_tag( name, value, html\_options) ### +Creates a hidden field. +``` +hidden_field_tag('something[interesting]', 5) => + + "" +``` + + +### img\_tag ### +Creates an image tag. +``` +img_tag('/some.png', 'something') => "something" +``` + + +### input\_field\_tag ### +Creates an input field tag. +``` +input_field_tag('something[interesting]', 5) => + + "" +``` + + +### is\_current\_page ### +Returns true if the url equals location.href or location.pathname, false if otherwise. +``` +is_current_page('yahoo.com') => false +``` + + +### link\_to ### +Creates a link to another page. +``` +link_to('hello world', '/something/here') => "hello world" +``` + + +### submit\_link\_to ### +Creates a submit button that links to another page. +``` +submit_link_to('holla', '/new/location') => + + "" +``` + + +### link\_to\_if(condition, name, url, html\_options, post, block) ### +Just like link\_to if the condition is true. If condition is false it returns name. + +### link\_to\_unless(condition, name, url, html\_options, block) ### +Just like link\_to if the condition is false. If condition is true it returns name. + +### link\_to\_unless\_current(name, url, html\_options, block) ### +Just like link\_to if the url passed in matches the current pages url. Returns name if otherwise. + +### password\_field\_tag ### +Returns a password field. +``` +password_field_tag('something[interesting]', 5) => + + "" +``` + + +### select\_tag ### +Returns a select tag. +``` +var choices = [ {value: 1, text: 'First Choice' }, + {value: 2, text: 'Second Choice'}, + {value: 3, text: 'Third Choice'} ] +select_tag('mySelectElement', 2, choices) => + + "" +``` + + +### single\_tag\_for ### + +Helper for creating a single tag like
+ +### start\_tag\_for ### + +Helper for creating a beginning tag like
+ +

submit_tag

+Creates a submit tag.
+
submit_tag('Submit') => "<input type=\'submit\' value=\'Submit\' />"
+
+

tag

+ +Creates a general tag.
+
+

tag_end

+ +Creates an end tag like
+ +### text\_area\_tag ### +``` +text_area_tag('task[description]', 'Here is some text.\nA new line.') => + "" +``` + + +### text\_field\_tag ### +``` +text_field_tag('something[interesting]', 5) => + "" +``` + + +### url\_for ### + +returns a string that changes the url. \ No newline at end of file