dotfiles/vim/bundle/eclim/doc/vim/python/django.txt

*vim-python-django*

Django
******

*:DjangoManage*


Django manage.py
================

For each project you create with the django framework, django provides
you with a manage.py which can be used to perform various tasks.  To
make the invocation of the manage.py script even easier, eclim
provides the command :DjangoManage which can be invoked from any file
in the same directory as your manage.py or in any of the child
directories.

:DjangoManage supports all the same commands as manage.py and supports
command line completion of command names and app names where
supported.

Several of the manage.py commands simply perform an action without
generating much if any output.  However there is also a set of
commands which generate sql statements.  For all of these commands,
instead of just running the command in a shell, :DjangoManage will run
the command and populate a new buffer with the resulting output and
set the proper file type.


Configuration
=============

Vim Settings (|vim-settings|)

*g:EclimDjangoAdmin*

- g:EclimDjangoAdmin (Default: 'django-admin.py') - This setting
  specifies the location of your django-admin.py file. By default it
  will attempt to locate it in your system path, but you can
  optionally set an absolute path for eclim to use. Eclim currently
  only needs access to this script when running :DjangoManage
  startproject <project_name> [destination]. All other :DjangoManage
  commands will use your project's manage.py.

Django python support
=====================

*:DjangoTemplateOpen*

Locating templates
   The command :DjangoTemplateOpen supports finding and opening a
   template referenced under the cursor.

   Ex.

   >

      # w/ cursor on 'mytemplates/mytemplate.html'
      return render_to_response('mytemplates/mytemplate.html', ...)

   <


*:DjangoViewOpen*

Locating views
   The command :DjangoViewOpen supports finding and opening a view
   referenced under the cursor.

   Ex.

   >

      # w/ cursor on 'myproject.myapp.views' or 'my_view' on the second line.
      urlpatterns = patterns('myproject.myapp.views',
          (r'^$', 'my_view'),
      )

   <


*:DjangoContextOpen*

Contextually locate file
   The command :DjangoContextOpen supports executing :DjangoViewOpen,
   :DjangoTemplateOpen, or :PythonSearchContext depending on the
   context of the text under the cursor.

Specifying the open command to use
   All of the above :Django*Open commands support an optional -a
   argument to specify the vim command used to open the result:

   - -a: The vim command to use to open the result (edit, split,
     tabnew, etc).
*htmldjango*


Django html template support
============================

Syntax
   Vim ships with a syntax file for django html template files, but
   eclim builds on that base to support highlighting of user defined
   tags and filters (see the configuration section below.

Indent
   Using the same settings as the enhanced syntax file, eclim also
   ships with an indent script which provides indentation support all
   of the default django tags and any user defined tags that have been
   configured.

Match It
   Again, using the same set of variables, eclim sets the necessary
   variables to allow proper matchit.vim support for django default
   and user defined tags.

End Tag Completion
   Using the |g:HtmlDjangoUserBodyElements| setting along with the
   pre-configured default list of body elements, eclim includes
   support for auto completion of ending template tags when you type
   an {%e or {% e.

*:DjangoFind*

Contextual Find
   While editing django html templates, the command :DjangoFind which
   will attempt to locate the relevant resource depending on what is
   under the cursor.

   - If on a user defined tag, attempt to find the tag definition
     within the python tag definition file.
     Ex.

     >
        {# w/ cursor on 'mytag' #}
        {% mytag somearg %}

     <

   - If on a user defined filter, attempt to find the filter
     definition within the python filter definition file.
     Ex.

     >
        {# w/ cursor on 'myfilter' #}
        {{ somevalue|myfilter }}

     <

   - If on the tag/filter definition portion of of a 'load' tag,
     attempt to find the definition file.
     Ex.

     >
        {# w/ cursor on 'mytags' #}
        {% load mytags %}

     <

   - If on a reference to a template for ethier an 'extends' or
     'include' tag, attempt to find that template file.
     Ex.

     >
        {# w/ cursor on 'include/mytemplate.html' #}
        {% include "include/mytemplate.html" %}

     <

   - If on static file reference, as defined in a 'src' or 'href'
     attribute of an element, attempt to find that static file.
     Ex.

     >
        {# w/ cursor on '/css/my.css' #}
        <link rel="stylesheet" href="/css/my.css" type="text/css" />

     <

     Note: this functionality requires that g:EclimDjangoStaticPaths
     is set to a list of absolute or django project relative (relative
     to directory containing manage.py and settings.py) directories,
     though it will fallback to using eclim's locate file
     functionality.

     Ex.

     >
        let g:EclimDjangoStaticPaths = ["../static/"]

     <

   Like the :Django*Open commands, :DjangoFind supports an optional -a
   <action> argument to specify the vim command used to open the
   resulting file.


Configuration
=============

Vim Settings (|vim-settings|)

*g:HtmlDjangoUserBodyElements*

- g:HtmlDjangoUserBodyElements - List of lists, where each list
  contains the name of the start and end tag, as well as any
  intermediary tags of any custom tags which have a body.
  Ex.

  >
     let g:HtmlDjangoUserBodyElements = [
         \ ['repeat', 'endrepeat'],
         \ ['try', 'except', 'finally', 'endtry'],
       \ ]

  <

  This setting is used for indentation of the custom tag's body, as
  well as arguments for proper matchit support, end tag completion,
  and syntax highlighting.

*g:HtmlDjangoUserTags*

- g:HtmlDjangoUserTags - This setting is a list of any non-body tags
  which don't require indentation or matchit support.  The items
  configured here will be used for syntax highlighting.
*g:HtmlDjangoUserFilters*

- g:HtmlDjangoUserFilters - This settings contains a list of any
  user defined django filters.  It is currently used for syntax
  highlighting.
*g:HtmlDjangoCompleteEndTag*

- g:HtmlDjangoCompleteEndTag (Default: 1) - When set to 0, disables
  the auto completion of end tags.
*g:EclimDjangoStaticPaths*

- g:EclimDjangoStaticPaths - Used as a list of directories to search
  when looking for static files (js, css, etc). Expected to be a list
  of absolute or django project relative (relative to directory
  containing manage.py and settings.py) directories.
  Ex.

  >
     let g:EclimDjangoStaticPaths = ["../static/"]

  <

*g:EclimDjangoStaticPattern*

- g:EclimDjangoStaticPattern - If you have a custom tag to load
  static files, then eclim by default may not be able to determine
  that it should be attempting to search for the static file
  referenced by that custom tag. In this case you can set
  g:EclimDjangoStaticPattern to a vim regular expression which matches
  your custom tag. For example, if you have a custom tag called static
  to load static files like so:
  >
     {% static 'lib/somefile.js' %}

  <

  Then you could set g:EclimDjangoStaticPattern to:

  >
     let g:EclimDjangoStaticPattern = "{%\\s*static(['\"]<element>['\"]"

  <

  Note that this pattern allows either ' or " to quote the static file
  path and since we are doing this we need to use double quotes around
  the pattern which in turn means that we need to double escape back
  slashes (note the double backslashes when matching 0 or more spaces:
  \\s*). Also note that the <element> portion of the pattern will be
  replaced with the path of the static file that eclim extracted while
  the cursor was over that portion of the tag.

*g:EclimDjangoFindAction*

- g:EclimDjangoFindAction (Default: "split") - For :DjangoFind and
  :DjangoTemplateOpen, used as the action to perform on the file
  found.

vim:ft=eclimhelp