Anonymous avatar Anonymous committed bab2d1a

Documentation.

Comments (0)

Files changed (5)

 URL generator
 -------------
 
+.. automodule:: akhet.urlgenerator
+
 .. autoclass:: akhet.urlgenerator.URLGenerator
-   :members:
+   :members: __init__, app, ctx, route, current, resource
    :undoc-members:
 
+   .. method:: __call__(\*elements, \*\*kw)
+
+      Same as the ``.route`` method.
+
 MultiDict
 ---------
 

docs/default_content.rst

+Default templates and stylesheet
+================================
+
+The default home page was redesigned in Akhet 1.0 final to be a simple base you
+can start with and add to if you wish. It consists of four files:
+
+* A home page, *zzz/templates/index.html*
+* A site template, *zzz/templates/site.html*
+* A stylesheet, *zzz/static/stylesheets/default.css*
+* A "reset" stylesheet, *zzz/static/stylesheets/reset.css*
+
+Both of the HTML files are Mako templates.
+
+index.html
+----------
+
+This is a page template. It contains just the HTML body, not the tags around it
+or the HTML header. Those will be added by the site template. The first three
+lines are Mako constructs:
+
+.. code-block:: mako
+   :linenos:
+
+    <%inherit file="/site.html" />
+    <%def name="title()">${project}</%def>
+    <%def name="body_title()">Hello, ${project}!</%def>
+
+Line 1 makes this template inherit from the site template. Lines 2 and 3 are
+Mako methods; these two return values which will be used by the site template.
+Line 2 is the title for the "<title>" tag. Line 3 is the title to display
+inside the page. 'project' is a variable the view method passes via its return
+dict. The rest of the default page is ordinary HTML so we won't bother showing
+it.
+
+Site template
+-------------
+
+The site template contains the "<html>" container tag and HTML header. The most
+important part is the "${self.body()}" placeholder, which is where the entire
+page template will go. Mako's 'self' construct takes the highest-level values
+available, allowing a page template to override default values in a parent
+template.
+
+The "<head>" section contains the usual title, character set, stylesheet, and
+the like. You can modify these as you wish. You can define a 'head_extra'
+method that returns a chunk of markup to insert into the header, such as more
+stylesheets or Javascript or metadata. At the bottom of the file are the
+default definitions of these methods. 'head_extra' and 'title' are empty by
+default, and 'body_title' deafaults to the same as 'title'.
+
+The "<body>" section contains a standardized header and footer; you can modify
+these as you wish to put the same doodads on all your pages. 
+
+There's also a stanza to display flash messages:
+
+.. code-block:: mako
+
+   <div id="content">
+   <div id="flash-messages">
+   % for message in request.session.pop_flash():
+       <div class="info">${message}</div>
+   % endfor
+   </div>
+
+Flash messages are a queue of messages in the session which are displayed on
+the next page rendered. Normally a view will push a success or failure message
+and redirect, and the redirected-to page will display the message. If you call
+'pop_flash' without a queue name, the default queue is used. This is enough for
+many programs. You can define multiple queues for different kinds of messages,
+and then pop each queue separately and display it in a different way. For
+instance:
+
+.. code-block:: mako
+
+    % for message in request.session.pop_flash("error"):
+        <div class="error">${message}</div>
+    % endfor
+    % for message in request.session.pop_flash("warn"):
+        <div class="error">${warning}</div>
+    % endfor
+
+Reset stylesheet
+----------------
+
+This is an industry-standard reset stylesheet by Eric Meyer, which is in the
+public domain. The original site is http://meyerweb.com/eric/tools/css/reset/ .
+It resets all the tag styles to be consistent across browsers. 
+
+The top part of the page is Meyer's original stylesheet; the bottom contains
+some overrides. Meyers does remove some attributes which have generally
+been assumed to be intrinsic to the tag, such as margins around <p> and <h\*>.
+His reasoning is that you should start with nothing and consciously re-add the
+styles you want. Some people may find this attitude to be overkill. The reset
+stylesheet is just provided as a service if you want to use it. In any case, we
+re-add some expected styles, and also set <dt> to bold which is a pet peeve of
+mine.
+
+If you want something with more bells and whistles, there's a stylesheet
+builder called `HTML5 Boilerplate`_, which some Pyramid developers recommend.
+It's also based on Meyer's stylesheet.
+
+.. _HTML5 Boilerplate: http://html5boilerplate.com/
+
+Default stylesheet
+------------------
+
+This is the stylesheet referenced in the page template; it inherits the reset
+stylesheet. It defines some styles we need for the default home page. The
+bottom section is styles for flash messages. The ".info" stanza is used by the
+default application; the ".warning" and ".error" styles are not used by default
+but are provided as extras.
    vocabulary
    paster
    architecture
+   default_content
    transaction_manager
    model_examples
    auth
    testing
    i18n
    migration
+   upgrading
    api
    other_pyramid_features
    bugs

docs/upgrading.rst

+Upgrading from pyramid_sqla
+%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+Here are the main differences between Akhet and its predecesor,
+pyramid_sqla. Because the name change affects all modules and their package
+name, it's probably easier to create a new Akhet application and paste your
+code into it than to try to modify your application in place.
+
+Name change, affecting the module name, and the metadata defined in setup.py.
+
+urlgenerator module is new.
+
+'url' was previously aliased to 'pyramid.url.route_url'. Chrism did
+that for preliminary Pylons compatibility. I didn't realize until
+later that that meant you had to pass the request as the second
+argument in every call.So i was going to change it to
+'request.route_url', but then somebody sent me a class that became
+URLGenerator, and I saw it as a more general solution.
+
+'handlers' and 'models' are packages rather than single modules, to
+facilitate larger applications
+
+'lib' package created and 'helpers.py' moved into it, to match
+Pylons and to give a place for non-helper extra code. Somebody was
+putting things into helpers.py that I didn't think were helpers and
+didn't belong under 'h'.
+
+You have to create the SQLAlchemy engines; add_engine() no longer
+does it. It was supporting three different use cases with different
+combinations of args (engine from settings, engine from explicit args,
+and preexisting engine), and it was so hard to document how these
+arguments interacted that I decided it was too much for one function.
+Following the rule, "If it's hard to document, it's a bad design."
+
+Change "[app:{{projectname}}]" in INI file to hardcoded
+"[app:myapp]". That's so you don't have to type the projectname in
+MixedCase every time you start pshell or another command-line tool.
+When you're developing several projects, it's easy to forget now this
+one is named and whether to use the ProjetName (mixed case) or package
+name (lower case). In Pylons you didn't need this arg because the app
+was always "main". Somebody on IRC complained that hardcoding it to
+"myapp" is a limitation, but to me it's a convenience for command-line
+scripts and I don't see a downside. Actually, I now think it would be
+best for PasteDeploy loadapp() to read all the sections and guess the
+name, because there's only one 'app' section, and it can start by
+assuming 'main' and then fall back to 'myapp', and abort if there are
+multiple 'app' sections. Because very few people have multiple 'app'
+sections. But that would require changing PasteDeploy. There is a move
+afoot to replace PasteDeploy/PasteScript/Paste with some thing(s)
+newer, but that's not soon enough for this.
+
+Switch to 'pyramid_tm' transaction manager from 'repoze.tm2'. The
+latter is new; I chose it because it's not a middleware, which makes
+the INI file less distorted. (I'm already unhappy that the need for a
+pipeline in the INI file prevents us from using '[app:main]', thus
+causing the previous problem.)
+
+'akhet/testts/make_test_app.sh' is a quick-and-dirty script to
+create a test application and run it. This is a stopgap until a more
+complete unittest library to create a virtualenv+app and test it is
+available. (Although this would be very slow with all of Pyramid's
+dependencies to install. I use a pip "download-cache" to mitigate
+this, but it still checks the latest versions on PyPI.)

unfinished/breadcrumbs.rst

+Breadcrumbs
+-----------
+
+The default application does not include this but several people have asked
+about it so here is my thoughts. Breadcrumbs are the navigation bar at the top
+of the page on many sites. 
+
+.. code-block: mako
+
+   Home > Section > Subsection > My Page
+
+The first three are links to ancestor pages, and the last one is just an
+abbreviation for the current page. In some variations, the last one is omitted.
+The bar gives users an intuitive way to see where they are in the site and to
+navigate upward. 
+
+Here's one way to do this in the site template:
+
+.. code-block:: mako
+
+   <%  crumbs = self.breadcrumbs()  %>
+   % if crumbs is not None:
+   <a href="${url.app}">Home</a>
+   % for link in self.breadcrumbs():
+   &nbsp;&gt;&nbsp;
+   ${link}
+   % endfor
+   % endif
+
+   <%def name="breadcrumbs()">
+   <%  return []  %>
+   <%/def>
+
+The breadcrumbs method has a Python "<% %>" escape which returns a Python
+value. This is not the method's HTML output: the output and the return value
+are different things. Mako methods don't return their HTML output, they write
+it. The "output" of this method is a blank line, which we never see because we
+don't call "${self.breadcrumbs()}".
+
+The default breadcrumbs method returns no crumbs, so only the Home link is
+shown. The Home link is always the same so we don't make every page define it.
+As a special case, if the method returns ``None``, the entire breadcrumbs bar
+is suppressed. This may be desirable on the home page or special pages.
+
+Then each page can define its crumbs like this, omitting the first Home crumb
+which is the same on every page. 
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.