docs: jinja

[srinify]

Adding some basic documentation on Jinja templating and how to use it!

[request-info]

We would appreciate it if you could provide us with more info about this issue/pr! Please do not leave the title or description empty.

[srinify]

[villebro]

Thanks for taking this on, this was long overdue! The section on cache_key_wrapper could be more precise. In addition, a description needs to be added to the PR.

[villebro]

cache_key_wrapper is nowadays applied by default to current_user_id and current_username (it can be disabled by calling them with add_to_cache_keys=False). See here for more context:

superset/superset/jinja_context.py

Lines 105 to 131 in efd7007

	def current_user_id(self, add_to_cache_keys: bool = True) -> Optional[int]:
	"""
	Return the user ID of the user who is currently logged in.
	:param add_to_cache_keys: Whether the value should be included in the cache key
	:returns: The user ID
	"""
	if hasattr(g, "user") and g.user:
	if add_to_cache_keys:
	self.cache_key_wrapper(g.user.get_id())
	return g.user.get_id()
	return None
	def current_username(self, add_to_cache_keys: bool = True) -> Optional[str]:
	"""
	Return the username of the user who is currently logged in.
	:param add_to_cache_keys: Whether the value should be included in the cache key
	:returns: The username
	"""
	if g.user and hasattr(g.user, "username"):
	if add_to_cache_keys:
	self.cache_key_wrapper(g.user.username)
	return g.user.username
	return None

cache_key_wrapper is therefore only needed when it's necessary to wrap your own custom function return values into the cache key. See here for more context:

superset/superset/jinja_context.py

Lines 133 to 148 in efd7007

	def cache_key_wrapper(self, key: Any) -> Any:
	"""
	Adds values to a list that is added to the query object used for calculating a
	cache key.
	This is needed if the following applies:
	- Caching is enabled
	- The query is dynamically generated using a jinja template
	- A `JINJA_CONTEXT_ADDONS` or similar is used as a filter in the query
	:param key: Any value that should be considered when calculating the cache key
	:return: the original value ``key`` passed to the function
	"""
	if self.extra_cache_keys is not None:
	self.extra_cache_keys.append(key)
	return key

[villebro]

Awesome work!