Download as
Browse Code »

Commit 71d6ad74ef26a3e2e480845bbfef99cf14fed0b9

Authored by Lucas Moura
1 parent fa271c26
Exists in master and in 4 other branches 1.12.x, fix-dashboard, fix-message-preview, validate-passwd

Add documentation for plugin search and highlight 

Signed-off-by: Lucas Moura <lucas.moura128@gmail.com>
Showing 1 changed file with 66 additions and 0 deletions   Show diff stats
docs/source/plugindev.rst
  Diff comments   View file @71d6ad7
... ... @@ -34,6 +34,7 @@ signals structure, some steps are required:
34 34 be seen below:
35 35  
36 36 .. code-block:: python
  37 +
37 38 from colab.celery import app
38 39  
39 40 @app.task(bind=True)
... ... @@ -48,6 +49,7 @@ signals structure, some steps are required:
48 49  
49 50  
50 51 .. code-block:: python
  52 +
51 53 from colab.plugins.utils.apps import ColabPluginAppConfig
52 54 from colab.signals.signals import register_signal, connect_signal
53 55 from colab.plugins.PLUGIN.tasks import HANDLING_METHOD
... ... @@ -71,6 +73,7 @@ signals structure, some steps are required:
71 73 \*\*kwargs. As you can see below:
72 74  
73 75 .. code-block:: python
  76 +
74 77 from colab.signals.signals import send
75 78  
76 79 send(signal_name, sender)
... ... @@ -78,4 +81,67 @@ signals structure, some steps are required:
78 81 * If you want to run celery manually to make some tests, you should execute:
79 82  
80 83 .. code-block:: shell
  84 +
81 85 colab-admin celeryC worker --loglevel=debug
  86 +
  87 +Search
  88 +----------
  89 +
  90 +In order to make some plugin model's searchable, it is necessary to create
  91 +some files. First of all, it is necessary to create a directory named "search"
  92 +inside the templates directory, that should be found on the plugin root
  93 +directory.
  94 +
  95 +Once the search folder exist, it is necessary to create a html file that will
  96 +describe how a model item will be displayed on the colab search page. This file
  97 +name must follow the pattern:
  98 +
  99 +MODELNAME_search_preview.html
  100 +
  101 +Where the MODELNAME should be the name of the model object that will be
  102 +represented on the html file. An example for this file can be seen bellow:
  103 +
  104 +.. code-block:: guess
  105 +
  106 + {% load i18n tz highlight gravatar date_format %}
  107 +
  108 + <div class="row">
  109 + <div class="col-md-2 center">
  110 + <a href="{% url 'user_profile' username=result.username %}">
  111 + {% block gravatar_img %}{% gravatar result.email 100 %}{% endblock gravatar_img %}
  112 + </a>
  113 + </div>
  114 + <div class="col-md-10">
  115 + <strong><a href="{% url 'user_profile' username=result.username %}">
  116 +
  117 + {% if query %}
  118 + <h4>{% highlight result.name with query %}</h4></a>
  119 + {% else %}
  120 + <h4>{{ result.name }}</h4></a>
  121 + {% endif %}
  122 +
  123 + </strong>
  124 + <small><strong>{% trans "Since" %}: {% date_format result.date_joined %}</strong></small><br>
  125 + <small>{% trans "Registered in" %}: <strong>{% trans "User" %}</strong></small><br>
  126 + </div>
  127 + </div>
  128 + <div class="row">
  129 + <hr>
  130 + </div>
  131 +
  132 +As can be seen in the above example, it also possible to highlight the elements being searched. This can be seen on
  133 +the following example:
  134 +
  135 +.. code-block:: html
  136 +
  137 + {% if query %}
  138 + <h4>{% highlight result.name with query %}</h4></a>
  139 + {% else %}
  140 + <h4>{{ result.name }}</h4></a>
  141 + {% endif %}
  142 +
  143 +It can be seen that if a query text was used on the search, it will highlight the element if it is present on the query, if not,
  144 +the element will be displayed without a highlight. Therefore, in order to highlight some fields, it is necessary
  145 +to first check if there is a query search. If there is, use the tag "highlight" before the field name. However, it
  146 +must be said that the highlight tag should be followed by a complement, such as "with query", as can be seen on the example
  147 +above. This complement is used to allow the highlight only if the attribute is actually present on the query used to perform a search.
... ...