EST8 är ett WordPress-plugin som importerar objekt från Vitec Express API till din WordPress-hemsida.
Objektinformationen importeras till egna posttyper och taxonomier, istället för att bara lagra json-filer, vilket förenklar integrationen i din WordPress-hemsida och öppnar upp möjligheten att använda många av de standardfunktioner som finns i WordPress. Alla fält sparas som custom fields / meta boxes. Mäklare sparas som egen posttyp. Bilder sparas lokalt i din WordPress-installations upload-mapp när de renderas för första gången.
Pluginet kommer med färdiga mallar för objektsidor och objektlistor. Det har också egna block / widgets till Gutenberg och sidbyggaren Elementor, där du enkelt via GUI kan skapa upp dina objektsidor.
Inställningarna för pluginet hittas under EST8 > Inställningar i WordPress-administrationen. De finns under tre flikar; Vitec API, Format, Import och Mallar.
Under den här fliken görs inställningar som rör kopplingen till Vitec Express API.
För att ansluta till API'et krävs ett konto i Vitecs Connect Portal, i det kontot kan ni hitta uppgifterna som behövs. Kontot behöver rättigheter till Kund ID, som tillhör mäklaren.
| Fält | Beskrivning |
|---|---|
| API URL | Domän för Vitec API, t.ex. https://connect.maklare.vitec.net. |
| API användarnamn | Användarnamn för API-kopplingen, t.ex. 578. |
| API lösenord | Lösenord för API-kopplingen, t.ex. C8tvaOKSkLs8srbIs3sorfDloZjqJskTYsaAo7T71tJUb2XTh4J. |
| Kund ID | Kundens ID, t.ex. M4872. |
Inställningar som rör olika format, exempelvis datumformat, titelformat och bildformat.
| Fält | Beskrivning |
|---|---|
| Titelformat | Ange vilket/vilka fält ni vill att titeln ska vara uppbyggd av. Titeln visas som rubrik på objektsidan och i titeln i webbläsaren t ex. Du anger fältnamnet inom måsvingar, t.ex. {salesHeadline}. Du kan använda grundläggande villkor för att bara visa ett fält och valfri text om det har ett värde, ett exempel på det kan vara: {salesHeadline?Rubriken är %value%} |
| Prisenhet | Enhet som visas efter priset. Används t.ex. i metoder som prettyPrice() används. |
| Ytenhet | Enhet som visas efter areor, exempelvis m² eller kvm. |
| Rumsenhet | Enhet som visas efter antal rum, exempelvis R.O.K.. |
| Prisformat | Hur ni vill att priset presenteras, kan vara 1 000 000, 1000000 eller 1.000.000. |
Alla tillgängliga värden kan hittas här.
| Fält | Beskrivning |
|---|---|
| Generellt | Generellt datumformat, exempelvis D j F. |
| Bud | Format på datumen för bud, exempelvis D j F, H:i. |
| Visning, start | Datum och tid för när visning börjar, exempelvis D j F, H:i. |
| Visning, slut | Datum och tid för när en visning är slut, exempelvis -H:i. |
| Visning utan tid | Format för visningar utan tid angiven, exempelvis D j F. |
Inställningar för olika bildstorlekar som hänvisas till i standardmallarna. Det finns 6 olika storlekar, tre vanliga och tre tumnaglar. Tumnaglar beskärs till exakt de mått som anges, vanliga bilder behåller sina proportioner men anpassas så de ej överstiger angivna mått.
Du kan även ställa in bildkvalitet här, tänk på att högre kvalitet innebär större filstorlek och långsammare sidladdning.
Välj vilka objekttyper och statusar ni vill visa på er hemsida. Viktigt att ni kryssar i alla typer och statusar ni vill visa någonstans på er hemsida.
Puginet kommer med standardmallar för arkivsida och objektsida som går att "modifiera" eller ersätta med egna mallar. Mallarna kan modifieras via inställningar i EST8-administrationen inuti WordPress-admin, eller via hooks (actions och filters).
Ni kan bygga egna mallar på olika sätt, antingen via kod eller sidbyggare, nedan förklarar vi hur. Vi rekommenderar att ni gör det via kod och skapar egna .php-filer i ert tema för mallarna om det inte räcker att använda våra inställningar, CSS och hooks. Det är ofta många olika villkor och scenarion som avgör vilken information som ska visas, som att vissa objekttyper och statusar ska visa vissa fält men inte andra. Detta kan vara svårt att få till via admingränssnittet i en sidbyggare.
Om ni använder våra standardmallar kan ni modifiera dom och lägga in eget innehåll via våra action- och filter-hooks.
- Visa alla hooks for objektsidor
- Visa alla hooks for objektlistor
För att se hur våra funktioner som används till varje hook är byggda kan ni titta i wp-content/plugins/est8/public/templates för inspiration och vägledning.
För att ändra innehållet i en mall via actions avregistrerar ni först pluginets egna funktion från önskad action, och anger istället er egen.
Alla våra funktioner har samma namn som action-hooken följt av "_default", exempelvis est8_template_single_object_header_default
- Visa alla hooks for objektsidor
- Visa alla hooks for objektlistor
<?php // reassign est8 hook functions on 'wp' action add_action('wp', function() { // remove plugin's default function from action remove_action('est8_template_single_object_summary','est8_template_single_object_summary_default', 10); // add your own function to action add_action('est8_template_single_object_summary','my_custom_summary_function', 10); }); // define your own custom function and output content function my_custom_summary_function() { $data = new EST8\Data(); $helper = new EST8\Helper(); $prices = $data->price(); echo '<div class="our-custom-content">'; echo '<h3>Behöver du låna ' . $helper->prettyPrice($prices->price) . '?</h3>'; echo '<a href="/kontakt/">Kontakta oss</a>'; echo '</div>'; } ?>
Filters används för att ändra exempelvis texter.
- Visa alla hooks for objektsidor
- Visa alla hooks for objektlistor
<?php
// define your own custom function and output content
add_filter( 'est8_filter_single_object_title', 'my_custom_object_titles_function' );
add_filter( 'est8_filter_archive_list_item_title', 'my_custom_object_titles_function' );
function my_custom_object_titles_function() {
$data = new EST8\Data();
return '<h2><span>' . $data->field('areaName') . ' </span>' . $data->field('streetAddress') . '</h2>';
}
?>För att skapa egna mallar via kod behöver ni skapa några nya PHP-filer i ert tema. De är archive-est8_object.php, single-est8_object.php och est8/list-est8_object.php.
| Filnamn | Beskrivning |
|---|---|
| single-est8_object.php | Sida för individuella objekt. Ska placeras direkt i din tema-mapp. |
| archive-est8_object.php | Objektlista med alla dina objekt. Filen inkluderar listan via $data->objectList() som i sin tur inkluderar list-est8_object.php. Ska placeras direkt i din tema-mapp. |
| est8/list-est8_object.php | Listar dina objekt och inkluderas som standard i archive-est8_object.php. Du kan själv inkludera listan genom att anropa $data->objectList() på valfri plats i ditt tema. Du kan också inkludera den via shortcoden [est8_objectlist]. Mer information om metoden och vilka argument som kan användas finns längre ner. Ska placeras i undermappen est8 i din tema-mapp. |
Pluginet har shortcodes för att inkludera objektlista på valfri plats och för att hämta fält från ett visst objekt.
För att enkelt kunna inkludera objektlistor på valfria sidor finns shortcoden [est8_objectlist]. Den tar vissa paramentrar där ni kan styra vilka statusar och objekttyper som ska visas och om det ska finnas filter ovanför listan eller inte.
För att se vilka parametrar som kan användas och vilka IDn som är tillgängliga, se metoden objectList()
| Parametrar | Beskrivning |
|---|---|
| status | Kommaseparerad lista med status IDn. |
| types | Kommaseparerad lista med objekttyps IDn. |
| filters | Om filter ska visas, sätt false om inga filter ska visas. För att ange vilka filter som ska visas ange kommaseparerad lista, se exempel nedan. |
| orderBy | Fält som listan ska sorteras på |
| order | Sorteringsordning |
| limit | Antal objekt som ska visas. |
// show houses only [est8_objectlist types="1"] // show sold objects only [est8_objectlist status="4"] // show 10 objects [est8_objectlist limit="10"] // show all objects without filters [est8_objectlist filters="false"] // show houses and farms that are for sale or upcoming, with all filters [est8_objectlist types="1, 5" status="3, 11" filters="types, municipality, status, bids, viewings, search"]
Den här shortcoden kan exempelvis användas om man bygger egna mallar via sidbyggare.
| Parametrar | Beskrivning |
|---|---|
| field | (Obligatoriskt) Fältet som ska hämtas, t.ex. "streetAddress" |
| format | Om innehållet ska formateras, kan lämnas tomt eller ha "price" som värde. |
| post_id | ID på posten, om inget anges tas värdet från get_the_ID(). |
// show street address [est8_data field="streetAddress"] // show starting price [est8_data field="startingPrice" format="price"]
Pluginet innehåller fyra klasser med metoder för att hämta, organisera, snygga till och spara information. Klasserna är Data, Helper, Form och Settings.
En instans behöver skapas till klassen innan en metod kan anropas, exempelvis $data = new EST8\Data();. Nedan beskrivs de vanligaste metoderna i respektive klass som du kan ha nytta av när du bygger din egna mall.
För att hämta objektinformation används metoder i klassen Data.
Returnerar string, int, bool eller array beroende på vilket fält som hämtas.
| Parametrar | Beskrivning |
|---|---|
| string $fieldName | Namnet på fältet du vill hämta. |
| int $postId | (Valfritt) ID på posten du vill hämta fältet från. ID-numret gäller WordPress-postens ID, inte Vitecs egna IDn. Om inget anges utgår den från ID-numret som returneras i get_the_ID(). |
<?php // create class instance $data = new EST8\Data(); // echo street address echo $data->field('streetAddress'); ?>
Returnerar string, sökväg till bilden.
| Parametrar | Beskrivning |
|---|---|
| string $imageId | Vitecs ID på bilden. |
| mixed $width/alias | Kan vara tre olika typer av värden:
|
| mixed $height | (Valfritt) Kan vara två olika typer av värden:
|
| boolean $crop | (Valfritt) Om bilden ska beskäras enligt bredd / höjd eller om bilden ska anpassas så den inte överstiger angiven bredd eller höjd. |
<?php // create class instance $data = new EST8\Data(); // get the cover image ID $coverImage = $data->field('coverImage'); // get the image url // this example uses the 'large' alias to get size defined in WP-admin // if image has not been rendered in this size before, it will be created // the loading time will be higher the first time an image is loaded // this is because it's processed and saved to your upload folder $imageUrl = $data->image($coverImage, 'large'); // show the image using printf, echo or $helper->echo() described below printf('<img src="%s" alt="" />', $imageUrl); // ------------------------------------------------------------------- // more examples of scaling and cropping images // ------------------------------------------------------------------- // this will create an image where the width does not exceed 900px $imageUrl = $data->image($coverImage, 900); // this will create an image where the width does not exceed 900px // and the height does not exceed 700px $imageUrl = $data->image($coverImage, 900, 700); // this will create a cropped image to the exact dimensions 900x700px $imageUrl = $data->image($coverImage, 900, 700, true); ?>
Returnerar int, lokal WP-posts ID.
| Parametrar | Beskrivning |
|---|---|
| string $brokerVitecId | Vitecs ID-nummer på mäklaren. |
<?php // create class instance $data = new EST8\Data(); // get primary broker's vitec id using the field()-method // each object has a primary and secondary broker $primaryBrokerVitecId = $data->field('primaryBroker'); // get primary broker's local wordpress id // to use when calling the field()-method to get broker details $primaryBrokerLocalId = $data->broker($primaryBrokerVitecId); // use the id to get the details echo $data->field('brokerName', $primaryBrokerLocalId); ?>
Returnerar array, innehållande price, highestPrice, highestBid, finalPrice, startingPrice och priceHeadline.
Metoden returnerar slutpriset som highestPrice om objektet är sålt. Annars jämförs utgångspriset med högsta budet, förutsatt att budgivning är offentlig, där det högsta värdet av de två returneras som highestPrice.
Värdena price och priceHeadline baseras på inställningen Pristyp som kan göras under EST8 > Inställningar > Mallar. Det är dessa två värden som visas i våra standardmallar.
| Parametrar | Beskrivning |
|---|---|
| int $postId | (Valfritt) ID på posten du vill hämta priset från. ID-numret gäller WordPress-postens ID, inte Vitecs egna IDn. Om inget anges utgår den från ID-numret som returneras i get_the_ID(). |
<?php // create class instance $data = new EST8\Data(); // get the price array $priceArr = $data->price(); // show price based on Template Settings printf('%s: %s', $priceArr['priceHeadline'], $priceArr['price']); // show the highest or final price printf('Pris: %s', $priceArr['highestPrice']); // show the starting price printf('Utgångspris: %s', $priceArr['startingPrice']); // show the highest bid printf('Högsta bud: %s', $priceArr['highestBid']); // show the final price printf('Slutpris: %s', $priceArr['finalPrice']); ?>
Skapar objektlista, utgår från mallen list-est8_object.php
| Parametrar | Beskrivning |
|---|---|
| array $args | (Valfritt) Array med villkor för visning, t ex vilka objekttyper och status som ska visas samt i vilken ordning objekten ska listas. Se tabellen nedan för mer information om denna arrays innehåll. |
array $args
| Nyckel | Värde |
|---|---|
| status | Array eller kommaseparerad lista med status IDn. Om inget anges faller den tillbaka på inställningarna under EST8 > Inställningar > Import i WP-admin. Olika kunder hos Vitec kan ha olika statusar att välja på. Via ert kundnummer kan ni se vilka ni har ett välja på (kundnummer kan börja på M eller S, vilket avgör vilka statusar ni har).
Tillgängliga status ID'n oavsett kundnummer:
För kundnummer som börjar på M:
För kundnummer som börjar på S: |
| types | Array eller lista med objekttyps IDn. Om inget anges faller den tillbaka på inställningarna under EST8 > Inställningar > Import i WP-admin.
Tillgängliga objekttyps ID'n: |
| orderby | Fält att ordna efter. Om inget anges används firstPublished. |
| order | Sorteringsordning.
Tillgängliga värden: |
| limit | Max antal poster som ska returneras. Om inget anges returneras alla träffar. |
<?php // create class instance $data = new EST8\Data(); // create arguments (optional) $args = array( 'status' = array(3, 10), 'types' = array(0, 1), 'orderby' = 'firstPublished', 'order' = 'DESC', 'limit' => 10 ); // include object list $data->objectList($args); ?>
Diverse metoder för textformatering och andra hjälpmedel hittas i klassen Helper.
Skriver ut formaterad sträng om värden finns, använder sig av sprintf(). Första parametern $output kan innehålla en fast sträng utan följande värden eller mönster med placeholders för följande värden. Om mönster används men följande värden är tomma skrivs inget ut. Praktiskt att använda för att slippa göra kontroller om ett värde finns innan man skriver ut en sträng.
| Parametrar | Beskrivning |
|---|---|
| string $output | Strängen som ska skrivas ut. Kan vara mönster om andra värden anges som argument. |
string $value1, $value2, $value3... | (Valfritt) Värden som ska användas i mönster i första argumentet $output. |
<?php // create class instances $helper = new EST8\Helper(); $data = new EST8\Data(); // show street address if not empty value $helper->echo('Gatuadress: %s', $data->field('streetAddress')); // can be used with just the value, if empty it won't output anything $helper->echo($data->field('streetAddress')); // multiple values can also be used, will output if any of them is found $helper->echo( '<a href="mailto:%2$s">%1$s</a>', $data->field('brokerName'), $data->field('brokerEmail') ); ?>
Formaterar priset enligt formatet angivet i EST8 > Inställningar > Format.
Om $showCurrencyUnit är true läggs också prisenheten på, som även den anges under Inställningar > EST8 Inställningar > Format.
| Parametrar | Beskrivning |
|---|---|
| string $price | Priset som ska formateras. |
bool $showCurrencyUnit | true eller false, om prisenhet, exempelvis kr, ska läggas till på slutet. |
<?php // create class instances $helper = new EST8\Helper(); $data = new EST8\Data(); // output formated price // with the default settings '1000000' will be changed to '1 000 000 kr' echo $helper->prettyPrice($data->field('startingPrice'), true); ?>
Returnerar array med kommande visningar.
| Parametrar | Beskrivning |
|---|---|
| array $allViewings | Array med alla visningar. |
<?php // create class instances $helper = new EST8\Helper(); $data = new EST8\Data(); // get all viewings $allViewings = $data->field('viewings'); // get upcoming viewings $upcomingViewings = $helper->getUpcomingViewings($allViewings); // loop through viewings foreach ($upcomingViewings as $viewing) { // show $viewing data } ?>
Gör om ny rad till paragraph.
| Parametrar | Beskrivning |
|---|---|
| string $text | Texten som ska formateras. |
<?php // create class instances $helper = new EST8\Helper(); $data = new EST8\Data(); // create paragraphs where new lines are found in sales description echo $helper->nl2p($data->field('longSalesDescription')); ?>
Returnerar array med två värden, lead och body. Metoden hämtar ut paragrapher ur texten och returnerar den första som lead och resterande som body. Om bara en paragraph hittas returneras den som antingen lead eller body, beroende på värdet i $returnAsLead.
| Parametrar | Beskrivning |
|---|---|
| string $text | Obligatorisk Texten som ska formateras. |
| bool $returnAsLead | Behöver inte anges, standardvärdet är true. Om true och bara en eller inga paragrapher hittas returneras hela texten som lead. Om false och bara en eller inga paragrapher hittas returneras hela texten som body. |
<?php // create class instances $helper = new EST8\Helper(); $data = new EST8\Data(); // text to be formatted $text = '<p>Aliquam neque augue, viverra at tempor quis, fermentum nec turpis. Nulla sed magna velit. In in tellus ante. Cras vel orci at orci tempus ullamcorper. Pellentesque finibus purus est, imperdiet finibus enim venenatis vitae.</p><p>Ut ut venenatis justo. Praesent viverra et nunc a vehicula. Proin viverra magna laoreet nisi tempor facilisis. Sed neque tellus, mattis vel ornare ut, aliquam sit amet arcu. Praesent et risus vitae arcu vehicula volutpat. Donec enim felis, volutpat nec imperdiet quis, dignissim vitae magna.</p>'; // split paragraphs and return array $textArr = $helper->splitLead($text); // show lead and body $helper->echo('<div class="lead">%s</div>', $textArr['lead']); $helper->echo('<div class="body">%s</div>', $textArr['body']); ?>
För att hämta en inställning gjord i WordPress-admin används klassen Settings.
Hämtar värdet för en inställning.
| Parametrar | Beskrivning |
|---|---|
| string $settingName | Namnet på inställningen, tillgängliga namn är: priceUnit, spaceUnit, roomsUnit, dateFormat, timeFormat, dateTimeFormat, imageSizes, lastImport, objectIds, statusIds |
<?php // create class instances $settings = new EST8\Settings(); $data = new EST8\Data(); // get date format $dateFormat = $settings->get('dateFormat'); // show current date with settings format echo wp_date($dateFormat); ?>
Metoder för att skicka formulär via klassen Form. Metoderna använder sig av wp_mail(), du behöver själv konfigurera ev. SMTP och autentisering.
Returnerar string, statuskod. Sparar intresseanmälan i Vitec och skickar mail till mäklaren / kontaktperson.
| Parametrar | Beskrivning |
|---|---|
| string $subject | Obligatorisk Mailet ämne |
| string $firstName | Obligatorisk Förnamn på intressenten |
| string $lastName | Obligatorisk Efternamn på intressenten |
| string $email | Obligatorisk E-post till intressenten |
| string $phone | Obligatorisk Telefon till intressenten |
| string $message | Ev. meddelande från intressenten |
| string $objectId | Obligatorisk Vitecs objekt ID |
| string $url | URL som mailet skickas från, t.ex. en objektsida. |
| string $to | Obligatorisk om $brokerId saknas E-postadress till mottagaren av mailet. Denna eller $brokerId måste anges. Om ingen e-post anges för $to hämtas e-post till mäklaren baserat på $brokerId. |
| string/int $brokerId | Obligatorisk om $to saknas Mäklarens ID. Antingen ID hos Vitec eller ID i er webbplats. |
<?php // create class instances $form = new EST8\Form(); // create variables with values $subject = 'Intresseanmälan: Gatuvägen 14, Staden'; $firstName = 'Sven'; $lastName = 'Svensson'; $email = 'sven@svensson.se'; $phone = '070 555 555 55'; $message = 'Hej, jag är intresserad av den här bostaden!'; $objectId = 'OBJ16336_1775547461'; $url = 'https://maklaren.se/objekt/gatuvagen-14-staden'; $to = 'lena@maklaren.se'; $brokerId = 14; // save to vitec and send e-mail to broker $response = $form->sendInterestForm( $subject, $firstName, $lastName, $email, $phone, $message, $objectId, $url, $to, $brokerId ); // show message switch ($response) { // on success case "success": echo "Tack för din anmälan!"; break; // on error while sending, more details can // be found in mail.log in your website's root folder case "error": echo "Ett fel uppstod."; break; // on validation error, could be missing fields or invalid e-mail case "invalid_data": echo "Kontrollera att alla fält är ifyllda korrekt."; break; } ?>
Returnerar string, statuskod. Skickar mail till mäklaren / kontaktperson.
| Parametrar | Beskrivning |
|---|---|
| string $subject | Obligatorisk Mailet ämne |
| string $firstName | Obligatorisk Förnamn på intressenten |
| string $lastName | Obligatorisk Efternamn på intressenten |
| string $email | Obligatorisk E-post till intressenten |
| string $phone | Obligatorisk Telefon till intressenten |
| string $address | Obligatorisk Gatuadress till intressenten |
| string $zip | Obligatorisk Postnummer till intressenten |
| string $message | Ev. meddelande från intressenten |
| string $url | URL som mailet skickas från, t.ex. en objektsida. |
| string $to | Obligatorisk om $brokerId saknas E-postadress till mottagaren av mailet. Denna eller $brokerId måste anges. Om ingen e-post anges för $to hämtas e-post till mäklaren baserat på $brokerId. |
| string/int $brokerId | Obligatorisk om $to saknas Mäklarens ID. Antingen ID hos Vitec eller ID i er webbplats. |
<?php // create class instances $form = new EST8\Form(); // create variables with values $subject = 'Kostnadsfri värdering'; $firstName = 'Sven'; $lastName = 'Svensson'; $email = 'sven@svensson.se'; $phone = '070 555 555 55'; $message = 'Hej, jag är intresserad av den här bostaden!'; $address = 'Gatuvägen 14'; $zip = '110 00'; $url = 'https://maklaren.se/objekt/gatuvagen-14-staden'; $to = 'lena@maklaren.se'; $brokerId = 14; // save to vitec and send e-mail to broker $response = $form->sendValuationForm( $subject, $firstName, $lastName, $email, $phone, $message, $address, $zip, $url, $to, $brokerId ); // show message switch ($response) { // on success case "success": echo "Tack för ditt mail!"; break; // on error while sending, more details can // be found in mail.log in your website's root folder case "error": echo "Ett fel uppstod."; break; // on validation error, could be missing fields or invalid e-mail case "invalid_data": echo "Kontrollera att alla fält är ifyllda korrekt."; break; } ?>