Rating modul

Slouží k evidenci hodnocení a počtu shlédnutí. Použít lze pod článkem nebo například u produktu v eshopu.

KonfiguraceZkopírovat odkaz na sekci

Rating modul se aktivuje v rámci sitemapy tagem:

1<ratingmodule>2  ...3</ratingmodule>

Možnosti nastavení modulu jsou shrnuty v následujících odstavcích.

CacheZkopírovat odkaz na sekci

Zapíná cachování. Pokud není explicitně použit konfigurační tag, vytvoří se cache s defaultními parametry. Její tag by vypadal takto:

1<cache threshold="0.5" ttl="180"/>

Tato cache se používá pouze pro starý přístup. Pro detailní hodnocení a jeho providery nefunguje.

ŠkálaZkopírovat odkaz na sekci

Nastavuje rozsah hodnocení.

1<scale from="1" to="5"/>

DetailedZkopírovat odkaz na sekci

Slouží pro detailnější logování hlasů. Umožňuje udržovat spolu s číselným hodnocením i textové. Přidává tedy možnost evidovat pozitivní a negativní textové hodnocení a reakci administrátora. Dále aktivací této součásti umožníte výpočet detailnějších statistik hodnocení. V neposlední řadě umožňuje i administraci z EDEEho a příslušný schvalovací proces pro nově přidaná hodnocení. Hodnocení lze i logicky mazat.

1<detailed defaultStatus="ACTIVE"/>

Možnosti defaultStatusu jsou:

• ACTIVE - hodnocení je vidět na frontendu okamžitě po vložení
• HIDDEN - hodnocení je po vytvoření vidět jen v EDEEm a čeká na schválení
• DELETED - hodnocení je logicky smazané (uvedeno jen aby zde byly všechny varianty, jako hodnota konfiguračního parametru nedává smysl)

AuditořiZkopírovat odkaz na sekci

Aktivuje specifické funkce pro evidenci hlasů a povolování přidání nového hlasu. Příklad kompletního nastavení auditorů i s defaultními hodnotami:

1<auditors typePatterns="">2    <auditor type="cookie" maxAge="7d" typePatterns=""/>3    <auditor type="ip" maxLimit="5" typePatterns=""/>4    <auditor type="captcha" auditRates="true" auditHits="true" typePatterns=""/>5    <auditor type="user" typePatterns=""/>6</auditors>

Všichni auditoři jsou volitelní, pouze pokud tag <auditors> chybí úplně, je automaticky aktivován Cookie auditor s defaultními parametry. Společným parametrem pro hlavní i vnořené tagy je typePatterns.

CookieZkopírovat odkaz na sekci

Blokuje další hlasování nebo hit pro prohlížeč s uloženým cookie po dobu jeho platnosti.

1<auditor type="cookie" maxAge="7d" typePatterns=""/>

IPZkopírovat odkaz na sekci

Blokuje další hlasování nebo přidání shlédnutí pro prohlížeč s daným IP po překročení limitu počtu přístupů.

1<auditor type="ip" maxLimit="5" typePatterns=""/>

CaptchaZkopírovat odkaz na sekci

Vyžaduje potvrzení zadání hodnocení nebo hitu pomocí captcha formuláře.

1<auditor type="captcha" auditRates="true" auditHits="true" typePatterns=""/>

UserZkopírovat odkaz na sekci

Eviduje hlasování podle uživatelského jména. Pro přihlášeného uživatele je tak možné přidat jen jedno hodnocení nebo navštívení stránky.

1<auditor type="user" typePatterns=""/>

Žádné specifické nastavení není třeba.

RatingZkopírovat odkaz na sekci

Umožňuje definovat jiné nastavení pro určitý typ ratingu. Nastavení pak vypadá stejně jako to globální. Všechny použitelné vnořené tagy jsou zahrnuty v příkladu, jen auditoři můžou být libovolní:

1<rating type="xxx">2  <scale from="1" to="5"/>3  <auditors>4      <auditor type="cookie" maxAge="7d"/>5  </auditors>6</rating>

GUIZkopírovat odkaz na sekci

Dále je třeba aktivovat administrační GUI. Tato část dává smysl pouze ve spojení s detailním logováním hlasů.

1<gui ramJetModuleName="edeeui"2                 parentSection="edee"3                 admin="true"4                 defaultSetup="true"/>

Denní ratingZkopírovat odkaz na sekci

Pro ukládání ratingHitů na denní bázi stačí aktivovat pomocí xml:

1<ratingmodule storeDaily="true" />

Modul bude nově ukládat a počítat hity po jednotlivých dnech - tabulka T_RATING_DAILY.

Prozatím ukládá pouze hits a defaultně je deaktivováno. Denní data lze získat pomocí programového přístupu přes metodu com.fg.rating.service.RatingService.getAllDailyHitRatings.

PříkladZkopírovat odkaz na sekci

Kompletní konfigurace může vypadat například takto:

1<ratingmodule storeDaily="true">2    <cache threshold="0.5" ttl="300"/>3    <scale from="1" to="5"/>4    <detailed defaultStatus="ACTIVE"/>5    <auditors>6        <auditor type="cookie" maxAge="365d"/>7        <auditor type="user"/>8    </auditors>9
10    <gui ramJetModuleName="edeeui"11         parentSection="edee"12         admin="true"13         defaultSetup="true"/>14</ratingmodule>

Propojení s frontendemZkopírovat odkaz na sekci

Vkládání informací do Rating modulu se provádí pomocí commandů. Alternativně lze využít i POST requestů na určitou adresu spojených s předáním parametrů.

CommandyZkopírovat odkaz na sekci

Počet shlédnutíZkopírovat odkaz na sekci

Provádí se pomocí commandu com.fg.rating.web.ramjet.HitCommand používaného pod typem jménem hit. Zároveň je k dispozici v Ramjetu na adrese /rating/hit. Jeho parametrem je pouze:

• ratedType - kombinace type;identifier, je jich možné použít i více a přidat tak hit k více položkám najednou

HodnoceníZkopírovat odkaz na sekci

Provádí se pomocí commandu com.fg.rating.web.ramjet.RateCommand známého pod jménem typu rate. Ten je k dispozici uvnitř Ramjetu na adrese /rating/rate. Parametry jsou tyto:

• ratedType - kombinace type;identifier, je jich možné použít i více a oratovat tak více položek najednou
• type - pokud není použit parametr ratedType složí jako první část kombinace v něm, určuje typ hodnocené položky, umožňuje oratování pouze jedné kombinace type-identifier najednou
• identifier - pokud není použit parametr ratedType složí jako druhá část kombinace v něm, určuje id položky v rámci typu
• rating - číselné hodnocení (celé číslo)
• userName - uživatelské jméno, pokud je uživatel přihlášen, bude použit jeho login na místo tohoto
• comment - komentář
• positiveComment - pozitivní hodnocení
• negativeComment - negativní hodnocení

POST requestyZkopírovat odkaz na sekci

Počet shlédnutíZkopírovat odkaz na sekci

Navýšení počtu shlédnutí se provede odesláním POST requestu na adresu:

1/rating/service/hit

Parametry POST requestu jsou:

• types - pole typů, u kterých se má zvýšit počet shlédnutí, např. [{"name":"views","identifier":"100"}]
  • typ se skládá ze dvou částí
    • name - jméno typu
    • identifier - ID identifikující položku v rámci typu

HodnoceníZkopírovat odkaz na sekci

Hodnocení se přidává POSTem na adresu:

1/rating/service/rate

Parametry takového POST requestu jsou:

• types - pole typů, ke kterým se má přidat dané hodnocení, např. [{"name":"views","identifier":"100"}]
  • typ se skládá ze dvou částí:
    • name - jméno typu
    • identifier - ID identifikující položku v rámci typu
• rating - číselné hodnocení
• userName* - jméno hodnotícího uživatele, ve formě:
  • čistý text se jménem, např. Martin Krása
  • uživatelské jméno interpretované frontendem, např. mkr
• positiveComment* - text pozitivního hodnocení
• negativeComment* - text negativního hodnocení

Položky označené hvězdičkou jsou funkční pouze v případě aktivního detailního logování hlasů.

Získávání výsledkůZkopírovat odkaz na sekci

Jednoduché výsledky lze získat pomocí GET requestů na adresu /rating/service/hit, resp. /rating/service/rate. Složitější statistiky lze získat pomocí data providerů.

Data provideryZkopírovat odkaz na sekci

Data providery mají smysl pouze v kombinaci s aktivním detailním logováním hlasů. Připravené jsou dva:

• com.fg.rating.web.ramjet.RatingResultRecordSource - slouží k získávání detailních statistik hodnocení daného typu
• com.fg.rating.web.ramjet.RatingDetailRecordListingSource - slouží k získávání jednotlivých hodnocení

RatingResultRecordSourceZkopírovat odkaz na sekci

Vrací objekt typu com.fg.rating.RatingResult obsahující statistiky hodnocení pro daný typ a identifikátor. Ukázka takovéhoto data sourcu:

1
2<dataSource class="com.fg.rating.web.ramjet.RatingResultRecordSource"3            ratedTypeRjel="products" identifierRjel="100" detailedRjel="true"/>

Data source ignoruje query a přijímá následující parametry:

Vrácený objekt obsahuje tyto data:

• ratedType - hodnocená položka com.fg.rating.RatedType, obsahuje:
  • name - hodnocený typ
  • identifier - identifikátor hodnocené položky v rámci typu
• rating - průměrné hodnocení
• totalVotes - celkový počet hodnocení
• valueResults - list com.fg.rating.RatingValueResult pro všechny jednotlivé hodnoty číselného hodnocení, vyplňuje se pouze pokud je nastaven parametr tagu detailedRjel="true", každá položka obsahuje:
  • rating - číselné hodnocení, ke kterému se záznam vztahuje
  • count - počet záznamů s tímto hodnocením
  • percentage - procento záznamů s tímto hodnocením ze všech hodnocení daného ratedType

RatingDetailRecordListingSourceZkopírovat odkaz na sekci

Lze použít pro získání právě jednoho detailu hodnocení nebo stránkovaného listu detailů hodnocení. Jako atributy přijímá standardní parametry query: filter, hint a order.

Pro použití v record listingu lze konfigurovat například takto:

1
2<recordListing id="ratingDetailListing"3               filter="and(4                           in(status, #widgetData[status.filter.value]!#),5                           in(ratedType, #widgetData[ratedType.filter.value]!#),6                           in(identifier, #widgetData[identifier.filter.value]!#),7                           in(rating, #widgetData[rating.filter.value]!#)8                       )"9               hint="paging(#params[pageNumber]!1#, 10)"10               order="order(#params[filter.orderBy]!created#, #params[filter.orderType]!asc#)">11    <dataSource class="com.fg.rating.web.ramjet.RatingDetailRecordListingSource"/>12    ...13</recordListing>

Pro použití v recordu pak lze použít například toto:

1
2<record id="ratingRecord"3        filter="eq(id, #params[ratingId]!?int#)">4    <dataSource class="com.fg.rating.web.ramjet.RatingDetailRecordListingSource"/>5    ...6</record>

Vrácené záznamy jsou pak instance třídy com.fg.rating.RatingDetail s atributy:

• id - primární klíč
• ratedType - hodnocená položka com.fg.rating.RatedType, obsahuje:
  • name - hodnocený typ
  • identifier - identifikátor hodnocené položky v rámci typu
• status - stav schválení hodnocení, enum com.fg.rating.RatingDetailStatus
  • ACTIVE - hodnocení je vidět na frontendu
  • HIDDEN - hodnocení je vidět jen v EDEEm a čeká na schválení
  • DELETED - hodnocení je logicky smazané
• rating - hodnocení
• userName - jméno hodnotícího uživatele, ve formě:
  • čistý text se jménem, např. Martin Krása
  • uživatelské jméno interpretované frontendem, např. mkr
• created - datum a čas vytvoření
• positiveComment - text pozitivního hodnocení uživatele
• negativeComment - text negativního hodnocení uživatele
• adminComment - text reakce administrátora

AdministraceZkopírovat odkaz na sekci

Ve stromu stránek, v sekci Rozšíření je položka Hodnocení. Jejím stiskem se dostanete do administrace Rating modulu.

Hlavní stránkaZkopírovat odkaz na sekci

Hlavní stránka obsahuje filtrovatelný seznam všech hodnocení.

S každým hodnocením je možné provést několik akcí:

• Upravit - otevírá podstránku Detail hodnocení
• Zveřejnit - převádí hodnocení ze stavu HIDDEN do stavu ACTIVE, to zpřístupní hodnocení na frontendu
• Schovat - převádí hodnocení ze stavu ACTIVE do stavu HIDDEN, to odstraní hodnocení z frontendu
• Odstranit - převádí hodnocení ze stavu ACTIVE nebo HIDDEN do stavu DELETED, to logicky smaže záznam z DB
• Vrátit z koše - převádí hodnocení ze stavu DELETED do stavu ACTIVE, ruší logické smazání v DB

Detail hodnoceníZkopírovat odkaz na sekci

Stránka zobrazuje všechny existující informace k danému hodnocení.

Dostupné akce jsou:

• Uložit - uloží upravenou hodnotu komentáře administrátora do DB
• Zveřejnit, Schovat, Odstranit, Vrátit z koše - ekvivalentní ke stejnojmenným akcím na Hlavní stránce

EventyZkopírovat odkaz na sekci

Modul vytváří po provedení určitých akcí eventy. Implementací listeneru tak lze provádět určité dodatečné akce, například rozeslat e-maily.

• com.fg.rating.event.RatingEvent - odesílá se po vytvoření záznamu pro rating
• com.fg.rating.event.HitEvent - odesílá se po vytvoření záznamu pro shlédnutí
• com.fg.rating.event.RatingAdminCommentEvent - odesílá se po úpravě komentáře administrátora
• com.fg.rating.event.RatingStatusChangedEvent - odesílá se po změně stavu hodnocení

Rating rest api moduleZkopírovat odkaz na sekci

Swagger dostupný z: lib_rating/src/main/resources/META-INF/doc/swagger/swagger.yaml

Ukazková konfigurace:

1<?xml version="1.0" encoding="utf-8"?>2<sitemap>3
4	<ratingmodule>5		<cache threshold="0.5" ttl="180"/>6		<scale from="1" to="5"/>7		<detailed defaultStatus="ACTIVE"/>8		<auditors>9			<auditor type="cookie"/>10		</auditors>11
12		<gui admin="true"/>13		<gui/>14	</ratingmodule>15
16
17    <module customName="ratingRestApi" classname="com.fg.rating.api.cps.RatingRestModule" />18</sitemap>19