Template tag and filter decorator fix

[jimhark]

I think the main page for this documentation is:

​http://docs.djangoproject.com/en/dev/howto/custom-template-tags/

But other pages may also need to be corrected.

When using register.filter() or register.tag() as a decorator, if you leave off the name argument, you still need the parentheses:

  @register.filter
  @stringfilter
  def lower(value):
      return value.lower()

Must instead be:

  @register.filter()
  @stringfilter
  def lower(value):
      return value.lower()

I figured this out by reading the source.

I notice the Django documentation tends not to be just simple reference, but incorporates lots of examples and best practices. For clarity and performance, I would write this as:

  makefilter = register.filter()
  
  @makefilter
  @stringfilter
  def lower(value):
      return value.lower()

And I'd use a similar approach to register.tag(). I urge you to consider this form when correcting the documentation. However, for the rest of this bug report I ignore this style issue and show the simplest fix.

Here are the rest of the changes:

Change:

  @register.filter
  def myfilter(value):
      return value
  myfilter.is_safe = True

To:

  @register.filter()
  def myfilter(value):
      return value
  myfilter.is_safe = True

Change:

  @register.filter
  def add_xx(value):
      return '%sxx' % value
  add_xx.is_safe = True

To:

  @register.filter()
  def add_xx(value):
      return '%sxx' % value
  add_xx.is_safe = True

Change:

  @register.tag
  def shout(parser, token):

To:

  @register.tag()
  def shout(parser, token):

Thanks,

Jim

[Karen Tracey]

I've not encountered any problem following the current docs, omitting parentheses. Therefore I believe the doc as it currently is is correct: parentheses are not required. What in the source gave you the impression that they are?

[jimhark]

Replying to kmtracey:

I've not encountered any problem following the current docs, omitting parentheses. Therefore I believe the doc as it currently is is correct: parentheses are not required. What in the source gave you the impression that they are?

Sorry then. Their must be something screwy in my configuration because after adding the parentheses the template system stopped crashing for us. I got the idea after looking at template/_init_.py in the Library.tag function which starts like this:

    def tag(self, name=None, compile_function=None):
        if name == None and compile_function == None:
            # @register.tag()
            return self.tag_function
        elif name != None and compile_function == None:
            if(callable(name)):
                # @register.tag
                return self.tag_function(name)

I read the if and it gave me the idea to add the parens which got my system working. Now reading further I see in the elif clause if "name" is callable it should just work without the parens. I'll be more careful before opening an issue in the future. Also if I can track down exactly what's causing the weird behavior on my system I'll post it here as a cautionary tail for others who might run into the same problem.

Thanks,

Jim