Permalink
Browse files

doc: A realy Big Batch of changes

Installation manual
Template manual (WIP)
Almost all cookbook items ported.
All leftover text files form within doc/ ported
Deployment manual
  • Loading branch information...
arjan committed Oct 26, 2012
1 parent f6f9fb9 commit a041a3e27fe25525ae6907337b605466f06a2f1f
Showing with 3,098 additions and 1,569 deletions.
  1. +0 −48 doc/Export-format.txt
  2. +0 −23 doc/INSTALL.varnish
  3. +0 −134 doc/Templates-and-scomps.txt
  4. +0 −19 doc/TextMateErlangBundleInstall.sh
  5. +0 −28 doc/UnitTesting.txt
  6. +0 −15 doc/UpgradeNotes
  7. +0 −121 doc/ZotonicCommands.txt
  8. +2 −0 doc/_static/overrules.css
  9. +0 −30 doc/contributing.md
  10. +35 −1 doc/dev/codestyle.rst
  11. +55 −0 doc/dev/documentation.rst
  12. +1 −0 doc/dev/index.rst
  13. +28 −0 doc/dev/testing.rst
  14. +0 −528 doc/development-notes.txt
  15. +3 −0 doc/glossary.rst
  16. +11 −0 doc/manuals/cli.rst
  17. +96 −0 doc/manuals/cookbook/admin-datetime.rst
  18. +152 −0 doc/manuals/cookbook/frontend-contactform.rst
  19. +54 −0 doc/manuals/cookbook/frontend-formupdating.rst
  20. +42 −0 doc/manuals/cookbook/frontend-growl.rst
  21. +68 −0 doc/manuals/cookbook/frontend-mod_chat.rst
  22. +47 −0 doc/manuals/cookbook/frontend-module-override.rst
  23. +134 −0 doc/manuals/cookbook/frontend-pagebackgrounds.rst
  24. +30 −0 doc/manuals/cookbook/frontend-retrieving-category.rst
  25. +134 −0 doc/manuals/cookbook/frontend-share-variable.rst
  26. +103 −0 doc/manuals/cookbook/frontend-signup-redirection.rst
  27. +50 −0 doc/manuals/cookbook/frontend-sitemap.rst
  28. +51 −0 doc/manuals/cookbook/frontend-sitespecific-signup.rst
  29. +39 −0 doc/manuals/cookbook/index.rst
  30. +44 −0 doc/manuals/cookbook/shell-activate-modules.rst
  31. +138 −0 doc/manuals/cookbook/shell-characters.rst
  32. +36 −0 doc/manuals/cookbook/shell-completion.rst
  33. +32 −0 doc/manuals/cookbook/shell-debuggingdatabase.rst
  34. +43 −0 doc/manuals/cookbook/shell-resetpassword.rst
  35. +106 −0 doc/manuals/cookbook/shell-restoring-db.rst
  36. +2 −1 doc/manuals/datamodel/resources.rst
  37. +0 −92 doc/manuals/deployment.rst
  38. +35 −0 doc/manuals/deployment/index.rst
  39. +20 −16 doc/{INSTALL.nginx → manuals/deployment/nginx.rst}
  40. +173 −0 doc/manuals/deployment/privilegedports.rst
  41. +37 −0 doc/manuals/deployment/startup.rst
  42. 0 doc/{ → manuals/deployment}/varnish.launchd.plist
  43. +47 −0 doc/manuals/deployment/varnish.rst
  44. 0 doc/{ → manuals/deployment}/varnish.zotonic.vcl
  45. +53 −0 doc/manuals/dispatch.rst
  46. +138 −0 doc/manuals/i18n.rst
  47. +7 −6 doc/manuals/index.rst
  48. +75 −0 doc/manuals/templates/actions.rst
  49. +49 −0 doc/manuals/templates/bestpractices.rst
  50. +70 −0 doc/manuals/templates/calling-zotonic.rst
  51. +14 −0 doc/manuals/templates/filter.rst
  52. +21 −0 doc/manuals/templates/identifiers.rst
  53. +31 −261 doc/manuals/templates/index.rst
  54. +12 −0 doc/manuals/templates/lookups.rst
  55. +37 −0 doc/manuals/templates/models.rst
  56. +157 −0 doc/manuals/templates/tags.rst
  57. +19 −0 doc/manuals/templates/validators.rst
  58. 0 doc/{ → manuals}/zotonic.sh
  59. +1 −1 doc/ref/actions/action_growl.rst
  60. +1 −1 doc/ref/index.rst
  61. +2 −3 doc/ref/modules/mod_acl_simple_roles.rst
  62. +50 −1 doc/ref/modules/mod_admin.rst
  63. 0 doc/{tpl/admin → ref/modules/mod_admin}/README
  64. +1 −1 doc/{tpl/admin → ref/modules/mod_admin}/README.i18n
  65. 0 doc/{tpl/admin → ref/modules/mod_admin}/_admin_dashboard_example.tpl
  66. 0 doc/{tpl/admin → ref/modules/mod_admin}/_admin_widget_i18n.tpl
  67. 0 doc/{tpl/admin → ref/modules/mod_admin}/_admin_widget_std.tpl
  68. +27 −0 doc/ref/modules/mod_backup.rst
  69. +1 −1 doc/ref/modules/mod_ssl.rst
  70. +58 −1 doc/ref/modules/mod_translation.rst
  71. +65 −1 doc/ref/templates/template_admin_edit_widget_i18n.rst
  72. +0 −4 doc/ssl.txt
  73. +0 −100 doc/template.gen_server
  74. +21 −0 doc/tutorials/_make_common.rst
  75. +0 −6 doc/tutorials/getting-started.rst
  76. +3 −2 doc/tutorials/index.rst
  77. +53 −0 doc/tutorials/install-addsite.rst
  78. +19 −0 doc/tutorials/install-troubleshooting.rst
  79. +71 −121 doc/tutorials/install.rst
  80. +149 −3 doc/tutorials/preinstall.rst
  81. +1 −0 doc/tutorials/site-anatomy.rst
  82. +7 −0 doc/tutorials/zotonic_status.rst
  83. +37 −0 src/models/m_rsc_export.erl
View
@@ -1,48 +0,0 @@
-
-%% the rsc_export() format, as returned by m_rsc:export/2
-
-[
- {id, 112233}, % Local ID
-
- %% Globally unique resource URI
- {uri, <<"http://www.example.com/id/112233">>},
-
- {rsc,
- %% Resource properties, e.g.:
- [{title, <<"Foo">>},
- ...
- ]
- },
-
- {medium,
- %% Medium properties, if the item has an embedded medium record.
- },
-
- {category,
- %% Category properties, if the item is a category.
- },
-
- {group,
- %% Group access properties (if item is a group)
- },
-
- {edges,
- %% Edges from this item to other items
- [
- % Every edge can contain:
- [ {id, 32432423} % local edge id
-
- {object_id, 223344}, % local object id
- {object_uri, <<"http://...">>},
- {object_title, <<"...">>},
-
- {predicate_id, 22}, % local predicate id
- {predicate_uri, <<"http://...">>},
- {predicate_title, <<"...">>},
-
- ]
-
- ]
- }
-]
-
View
@@ -1,23 +0,0 @@
-Varnish configuration for a Zotonic site
-========================================
-
-The file doc/varnish.zotonic.vcl is a very simple configuration file
-for varnish in which static content and the home page is cached and
-all page requests are handled by the Zotonic server (which does its
-own caching). All non recognized host names are send to Nginx (or
-Apache) on port 8080.
-
-On *nix:
- sudo varnishd -a :80 -T localhost:6082 -f varnish.zotonic.vcl -s malloc -u nobody
-
-On Mac OS X you need to use the varnish.launchd.plist.
- sudo cp varnish.zotonic.vcl /usr/local/etc/varnish/.
- sudo cp varnish.launchd.plist /usr/local/etc/varnish/.
- sudo chown root:wheel /usr/local/etc/varnish/*
- sudo launchctl load /usr/local/etc/varnish/varnish.launchd.plist
- sudo start launchd
-
-Or run varnishd in the foreground:
- sudo varnishd -F -a :80 -T localhost:6082 -f varnish.zotonic.vcl -s malloc -u nobody
-
-You might want to change the req.http.host and the backend names.
@@ -1,134 +0,0 @@
-= Templates and Scomps =
-
-The templates in Zotonic are based on django templates, using the excellent erlydtl library.
-See http://code.google.com/p/erlydtl/ for the implemented tags and release notes.
-
-== Template Locations ==
-
-The templates are searched for in two different locations:
-
-/zotonic/default/templates/
-/zotonic/priv/templates/
-
-Templates don't need to have an extension, they are just text files. Templates can also be found in subdirectories, as long as you give the subdirectory name with the template.
-
-
-== Scomps ==
-
-Scomp is shorthand for screen component. A scomp is a module implementing logic and templates.
-Scomps can be included in the template using, for example:
-
- {% @button text="Hello" action={growl text="Hello World" stay="1"} %}
- {% @button text=somevar action={growl text="Hello World" stay="1"} %}
-
-This button scomp has two parameters, text and action. The action parameter is a tuple with two additional parameters.
-
-
-== Implementing Scomps ==
-
-Scomps come in two different variations, caching and non-caching.
-
-You can implement scomps by using the behaviours scomp and caching_scomp.
-
-A scomp has the following four functions:
-
- init(Args) -> {ok, State} | {error, Error}
- render(Params, Context, State) -> {ok, NewContext} | {error, Error}
- code_change(OldVsn, State, Extra) -> {ok}
- terminate(Reason, State) -> ok
-
- State = term()
- Params = proplist()
- Context = context()
-
- depends(Params, Context) -> {NewParams, MaxAge, Depend} | false
-
- Params = proplist()
- MaxAge = integer()
- Depend = TermList()
-
-
-== Templates, Scomps and Request Context State ==
-
-During the evaluation of scomps we are able to:
-
-- wire action
-- add script
-- add validator
-- add variable (accessible only by other scomps)
-
-After rendering a template it is inspected to find all scripts, actions and validators. They are placed as #context records in the resulting iolist, the #contexts should be replaced by the 'render' record-attribute. There will be a special 'script' atom to signify the place where all collected scripts will be inserted. When the script atom is not found, then the result of the template
-is a context, unless there are no collected scripts.
-
-Process state diagram, how all processes work together to render a scomp:
-
-Resource Template ScompServer Scomp Page/Session/User
- |
- |------------> render(Template,ReqContext)
- |
- | ------------------------------- lookup missing var ---------->|
- |
- |<------------------------------------- value ------------------|
- |
- |------------------> render(Scomp,ReqContext)
- |
- |---------> render(ReqContext)
- : |
- (if cached) |
- : |
- |<--ReqContext--|
- |
- |
- |
- |
- |
- |<------------ Output ----------|
- |
- Filter scripts
- |
- |<---- Output ------|
- |
- reply user agent
-
-
-The scripts/actions/validators are similar to the ones defined with Nitrogen, though the record structure is redefined to accomodate easy construction by the Template compiler.
-
-
-== Things to do ==
-
-1. Change the variable lookup in erlydtl_runtime.erl - Done.
-2. Add extra parsing rules to erlydtl_parser.yrl - Done.
-3. Build the new LALR parser - Done.
-4. Add handling of scomp AST (abstract syntax tree) to erlydtl_compiler.erl - Done.
-5. Create the scomp server (no caching for the moment) - Done.
-6. Add script filter to z_template - Done.
-7. Make test scomps - Done.
-
-== Code generated for the scomp calls ==
-
-{% @button text="Hello" action={growl text="Hello World" stay=1} %}
-
-gives an AST of:
-
- [{scomp,
- {identifier,{5,5},"button"},
- [{{identifier,{5,12},"text"},
- {string_literal,{5,17},"\"Hello\""}},
- {{identifier,{5,25},"action"},
- {{identifier,{5,33},"growl"},
- [{{identifier,{5,39},"text"},
- {string_literal,{5,44},"\"Hello World\""}},
- {{identifier,{5,58},"stay"},
- {number_literal,{5,63},"1"}}]}}]},
-
-Which should be translated to:
-
- case z_scomp:render(button, [{text,"Hello"},
- {action, {growl, [{text,"HelloWorld"}, {stay,1}]} }
- ], Variables)
- of
- {ok, Rendered} -> Rendered;
- {error, Reason} -> io_lib:format("error: ~p", Reason)
- end
-
-
@@ -1,19 +0,0 @@
-#!/bin/sh
-
-LC_CTYPE=en_US.UTF-8
-SVN=`which svn`
-
-echo Changing to Bundles directory...
-mkdir -p "/Library/Application Support/TextMate/Bundles"
-cd "/Library/Application Support/TextMate/Bundles"
-
-if [ -d "/Library/Application Support/TextMate/Bundles/Erlang.tmbundle" ]; then
- echo Erlang bundle already exists - updating...
- $SVN up "Erlang.tmbundle"
-else
- echo Checking out Erlang bundle...
- $SVN --username anon --password anon co "http://svn.textmate.org/trunk/Bundles/Erlang.tmbundle"
-fi
-
-echo Reloading bundles in TextMate...
-osascript -e 'tell app "TextMate" to reload bundles'
View
@@ -1,28 +0,0 @@
-How to Unit test a Zotonic install.
----------------------------------
-
-Basic tests:
-
-./runtests.sh
-
-This starts the zotonic system and executes all EUnit tests.
-
-However, you will see a lot of failing tests, since the sandboxed test
-environment is not started by default, since this needs some setup
-regarding the database and hostname.
-
-The sandbox test environment is located at priv/sites/testsandbox, and
-behaves just like a regular zotonic site. Create a database like this:
-
-CREATE DATABASE zotonic_testsandbox WITH OWNER = zotonic ENCODING = 'UTF8';
-GRANT ALL ON database zotonic_testsandbox TO zotonic;
-
-Rename the priv/sites/testsandbox/config.in file to config, and edit
-it to setenabled = true, and adjust the database settings.
-
-Now, create a hosts entry pointing to localhost:
-127.0.0.1 testsandbox
-
-Now, when you start ./runtests.sh the tests which involve the
-testsandbox will be included. At this point you can also point your
-browser to http://testsandbox:8000/ to see the sandbox site.
View
@@ -1,15 +0,0 @@
-
-
-Upgrading to 0.5.x
-------------------
-
-* filters disappeared and changed into expression syntax: |eq, |ne, |lt,
- |gt, |not, etc.: adjust templates accordingly.
-
- e.g. {% if id|eq:2 %} becomes {% if id == 2 %}
-
-* meaning of hassubject', 'hasobject', 'hassubjectpredicate' and 'hasobjectpredicate' has been reversed:
- m.search[{query hasobject=id}] becomes m.search[{query hassubject=id}] (and reverse)
- m.search[{query hasobjectpredicate=id}] becomes m.search[{query hassubjectpredicate=id}] (and reverse)
-* resource_staticfile's root dir has changed from site/templates/xx to site/xx
-* m_group model no longer exists
View
@@ -1,121 +0,0 @@
-Zotonic Commands
-================
-The zotonic command can run a number of utility commands availble in
-zotonic/bin.
-
-OS X Compatibility Problem
---------------------------
-If you symlink to zotonic/bin/zotonic, then you will need GNU coreutils on
-OS X or `readlink -e` will fail. I could not find a clean work-around for
-this with built-in OS X CLI tools. This is needed to traverse deeply
-symlinked commands.
-
-
-zotonic addsite [options] <site_name>
--------------------------------------
-Create a new site with [site_name] as its name. This new site will be
-based on a so-called skeleton site. Currently there are two skeletons:
-'blog' and 'empty'. "blog" is the default.
-
-"zotonic addsite -s empty yoursite" creates a new site called
-"yoursite" based on the skeleton called "empty". Full usage:
-
-zotonic-addsite [options] <site_name>
-
- -s <skel> Skeleton site ('blog' or 'empty'; default: blog)
-
- -h <host> Database host (default: 127.0.0.1)
- -p <port> Database port (default: 5432)
- -u <user> Database user (default: zotonic)
- -P <pass> Database password (default: zotonic)
- -d <name> Database name (default: zotonic)
- -n <schema> Database schema (default: public)
- -a <pass> Admin password (default: admin)
-
-
-zotonic copysite [site_name] [source_server]
---------------------------------------------
-Copy [site_name] and its database content from the [source_server] over SSH
-and load its content into the filesystem and database of the local machine.
-
-You will need to have created the database zotonic_[site_name] for this to
-work.
-
-Warning: This command will reset the content of the database to the content
-retrieved from the [source_server]. It does, however, generate and output
-a restore file in case this was run by accident and explains how to recover.
-
-
-zotonic createdb [site_name]
-----------------------------
-Create a database called zotonic_[site_name] with the basic setup in place to
-host a Zotonic datastore.
-
-This script will likely need to be run as postgres unless zotonic has been
-granted CREATEDB in postgres as follows:
-
- ALTER ROLE zotonic WITH CREATEDB
-
-
-zotonic debug
--------------
-Launch the Zotonic server interactively and get an EShell on the
-running instance. There is a "start.sh" command in the root folder
-which is a shortcut for this command.
-
-
-zotonic restart
----------------
-Restart the background Zotonic server instance.
-
-
-zotonic shell
--------------
-Connect to the background Zotonic server instance and provide and EShell.
-
-
-zotonic sitedir [site_name]
----------------------------
-Get the absolute path for a site based on [site_name]
-
-
-zotonic snapshot [site_name]
-----------------------------
-Take a version control snapshot of [site_name] including its database content.
-
-This works differently from mod_backup in that it consistently uses the same
-filename for the SQL backup to make revision-based full site rollbacks
-possible.
-
-
-zotonic start
--------------
-Start the background Zotonic server instance.
-
-
-zotonic stop
-------------
-Stop the background Zotonic server instance.
-
-
-zotonic update
---------------
-Update the server. Compiles and loads any new code, flushes caches and
-rescans all modules.
-
-
-zotonic compilefile [files...]
-------------------------------
-
-Compiles a single file within the zotonic folder. This runs very fast
-and works very well on a save-hook of your text editor. In Emacs, it
-would be called like this:
-
-(add-hook 'erlang-mode-hook
- '(lambda ()
- (add-hook 'after-save-hook '
- (lambda ()
- (call-process "/path/to/your/bin/zotonic" nil "*scratch*" nil "compilefile" buffer-file-name)
- )
- )
- ))
Oops, something went wrong.

0 comments on commit a041a3e

Please sign in to comment.