Add documentation for plugin search and highlight

Signed-off-by: Lucas Moura <lucas.moura128@gmail.com>

Add documentation for plugin search and highlight
Signed-off-by: Lucas Moura <lucas.moura128@gmail.com>
Lucas Moura
1 parent fa271c26
Showing 1 changed file with 66 additions and 0 deletions Show diff stats
docs/source/plugindev.rst
@@ -34,6 +34,7 @@ signals structure, some steps are required:
   be seen below:
 .. code-block:: python
+
    from colab.celery import app
    @app.task(bind=True)
@@ -48,6 +49,7 @@ signals structure, some steps are required:
 .. code-block:: python
+
    from colab.plugins.utils.apps import ColabPluginAppConfig
    from colab.signals.signals import register_signal, connect_signal
    from colab.plugins.PLUGIN.tasks import HANDLING_METHOD
@@ -71,6 +73,7 @@ signals structure, some steps are required:
   \*\*kwargs. As you can see below:
 .. code-block:: python
+
    from colab.signals.signals import send
    send(signal_name, sender)
@@ -78,4 +81,67 @@ signals structure, some steps are required:
 * If you want to run celery manually to make some tests, you should execute:
 .. code-block:: shell
+
    colab-admin celeryC worker --loglevel=debug
+
+Search
+----------
+
+In order to make some plugin model's searchable, it is necessary to create
+some files. First of all, it is necessary to create a directory named "search"
+inside the templates directory, that should be found on the plugin root
+directory.
+
+Once the search folder exist, it is necessary to create a html file that will
+describe how a model item will be displayed on the colab search page. This file
+name must follow the pattern:
+
+MODELNAME_search_preview.html
+
+Where the MODELNAME should be the name of the model object that will be
+represented on the html file. An example for this file can be seen bellow:
+
+.. code-block:: guess
+
+   {% load i18n tz highlight gravatar date_format %}
+
+    <div class="row">
+    <div class="col-md-2 center">
+        <a href="{% url 'user_profile' username=result.username %}">
+        {% block gravatar_img %}{% gravatar result.email 100 %}{% endblock gravatar_img %}
+        </a>
+    </div>
+    <div class="col-md-10">
+        <strong><a href="{% url 'user_profile' username=result.username %}">
+
+            {% if query %}
+                <h4>{% highlight result.name with query %}</h4></a>
+            {% else %}
+                <h4>{{ result.name }}</h4></a>
+            {% endif %}
+
+        </strong>
+        <small><strong>{% trans "Since" %}: {% date_format result.date_joined %}</strong></small><br>
+        <small>{% trans "Registered in" %}: <strong>{% trans "User" %}</strong></small><br>
+    </div>
+    </div>
+    <div class="row">
+    <hr>
+    </div>
+
+As can be seen in the above example, it also possible to highlight the elements being searched. This can be seen on
+the following example:
+
+.. code-block:: html
+
+    {% if query %}
+        <h4>{% highlight result.name with query %}</h4></a>
+    {% else %}
+        <h4>{{ result.name }}</h4></a>
+    {% endif %}
+
+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,
+the element will be displayed without a highlight. Therefore, in order to highlight some fields, it is necessary
+to first check if there is a query search. If there is, use the tag "highlight" before the field name. However, it
+must be said that the highlight tag should be followed by a complement, such as "with query", as can be seen on the example
+above. This complement is used to allow the highlight only if the attribute is actually present on the query used to perform a search.
	@@ -34,6 +34,7 @@ signals structure, some steps are required:		@@ -34,6 +34,7 @@ signals structure, some steps are required:
34	be seen below:	34	be seen below:
35		35
36	.. code-block:: python	36	.. code-block:: python
		37	+
37	from colab.celery import app	38	from colab.celery import app
38		39
39	@app.task(bind=True)	40	@app.task(bind=True)
	@@ -48,6 +49,7 @@ signals structure, some steps are required:		@@ -48,6 +49,7 @@ signals structure, some steps are required:
48		49
49		50
50	.. code-block:: python	51	.. code-block:: python
		52	+
51	from colab.plugins.utils.apps import ColabPluginAppConfig	53	from colab.plugins.utils.apps import ColabPluginAppConfig
52	from colab.signals.signals import register_signal, connect_signal	54	from colab.signals.signals import register_signal, connect_signal
53	from colab.plugins.PLUGIN.tasks import HANDLING_METHOD	55	from colab.plugins.PLUGIN.tasks import HANDLING_METHOD
	@@ -71,6 +73,7 @@ signals structure, some steps are required:		@@ -71,6 +73,7 @@ signals structure, some steps are required:
71	\\kwargs. As you can see below:	73	\\kwargs. As you can see below:
72		74
73	.. code-block:: python	75	.. code-block:: python
		76	+
74	from colab.signals.signals import send	77	from colab.signals.signals import send
75		78
76	send(signal_name, sender)	79	send(signal_name, sender)
	@@ -78,4 +81,67 @@ signals structure, some steps are required:		@@ -78,4 +81,67 @@ signals structure, some steps are required:
78	* If you want to run celery manually to make some tests, you should execute:	81	* If you want to run celery manually to make some tests, you should execute:
79		82
80	.. code-block:: shell	83	.. code-block:: shell
		84	+
81	colab-admin celeryC worker --loglevel=debug	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.