simorgh
Release 4.2049.0
BBC World Service News -Websites werden mit Simorgh, einer auf ReactJS basierenden Anwendung, gerendert. Simorgh rendert außerdem AMP -Nachrichtenseiten für Weltdienstleistungen, öffentliche Dienstnachrichten und BBC Sport.
Simorgh bietet jeden Monat ein schnelles und zugängliches Web -Erlebnis, das von Millionen von Menschen auf der ganzen Welt verwendet wird (siehe Liste der Websites mit Simorgh). Es wird regelmäßig gepflegt und gut dokumentiert, und wir begrüßen Open Source -Mitwirkende.
Simorgh wird hauptsächlich von den BBC News Web Engineering -Teams gepflegt. Es liefert sehr vertrauenswürdige Nachrichten an Leser auf der ganzen Welt, derzeit in (41 Sprachen). Wir unterstützen eine breite Palette von Geräten und sorgen Sie für Skalierung, Leistung und Zugänglichkeit. Wir arbeiten in agilen, flexiblen Teams und haben eine aufregende Roadmap für die zukünftige Entwicklung.
Bitte machen Sie sich mit unserem vertraut gemacht:
NB Es gibt weitere Dokumentationen mit relevantem Code. Die obige Liste ist ein Index der obersten Dokumentation unseres Repo.
Eine Anfrage an einen BBC -Artikel (https://www.bbc.co.uk/news/articles/clldg965yzjo) wird an die Simorgh -Anwendung von einem proprietären Routing- und Caching -Service (genannt Mozart) weitergegeben.
Die Anforderung entspricht einer Route in unserem Express -Server mit einer Regex -Übereinstimmung ( articleRegexPath || frontPageRegexPath ). Wenn die URL mit dem vordefinierten Regex-Muster für einen Artikel oder eine Titelseite übereinstimmt, holen wir einige Parameter von der Route mit der Funktion getRouteProps . Dies gibt den Dienst, den ISAM, der Route und die Match -Eigenschaften zurück. Route ist getInitialData React-Router-Route, ArticleContainer eine Methode zum Abrufen des ersten JSON definiert
Sobald die Daten zurückgegeben sind, ziehen wir den Statuscode und übergeben alle diese Daten als Requisiten mit renderDocument an unser Hauptdokument.
Das Dokument übergibt die URL, JSON -Daten, den BBC -Ursprung, den ISAMP und den Dienst an den Haupt -App -Container, und das Ergebnis wird unter Verwendung der React Own renderToString -Methode in eine Zeichenfolge übertragen. Diese Zeichenfolge wird dann zusammen mit dem Assets -Array, Style -Tags (die Ausgabe von gestalteten Komponenten) und allen Skripten/Links, die dem Kopf hinzugefügt werden müssen, an documentComponent als Haupt -App übergeben. Dies wird dann zu einem statischen HTML -Markup unter Verwendung von React Own renderToStaticMarkup und an den Benutzer als statische HTML zurückgeführt. In dieser Antwort sind Links zu unseren JS -Bundles enthalten, die ein Benutzer Gerät herunterladen, um die einseitige Anwendung (SPA) für nachfolgende Reisen zu starten.
Nachdem die RAW-HTML heruntergeladen wurde, beginnt die Client-Seite JS-Datei und hydratiert die anfängliche Antwort mit der Client-Seitenanwendung. Während dieses Prozesses verwendet React die anfängliche JSON -Nutzlast (verfügbar auf dem globalen Fensterobjekt SIMORGH_DATA ), um das von Reactdomserver zurückgegebene ursprüngliche Markup zu hydratieren. React erwartet, dass der gerenderte Inhalt zwischen dem Server und dem Client identisch ist (deshalb senden wir die anfängliche JSON -Nutzlast mit der SSR -Seite, sodass die Hydratationsphase mit denselben Daten ausgeführt wird, die der Server verwendet).
Die JSON -Nutzlast für einen Artikel besteht aus einer Reihe von Blöcken. Jeder Block ist ein Objekt, das ein Element auf der Seite darstellt. Dies kann eine Überschrift, ein Bild, einen Absatz usw. sein. Jeder dieser Blöcke hat einen Blocktyp und ein Blocktyp stimmt mit einem bestimmten Container in Simorgh, z.
Der Articlemain -Container wird über jeden JSON -Block iteriert, ihn gegen den entsprechenden React -Container übereinstimmen und die Daten über Props übergeben. In diesen Containern befindet sich die Logik für die Rendern jedes Blocktyps. An diesem Punkt verwenden wir die installierten Frontend -Komponenten aus der PsammaMad -Komponentenbibliothek. Zum Beispiel importiert der Bildbehälter den Abbildung Container und importiert und verwendet die PsammaMead-Image und die Psammammader-Image-Place-Hälter-Komponenten. Ein Bild in einem Artikel hat im Allgemeinen eine Bildunterschrift, sodass der Figurenbehälter den Bildunterschrift -Container importiert, der mehr Frontend -Komponenten von Psammammead umfasst, um eine Bildunterschrift auf dem Bild zu rendern.
Dieser Vorgang wird für jeden Block in einem Artikel wiederholt, wodurch der Hauptteil eines Nachrichtenartikels letztendlich eine Kombination von React -Behältern für die Geschäftslogik und React -Komponenten für das Frontend -Markup verwendet wird.
Jeder Render wird durch eine Reihe von HOCs (Komponenten höherer Ordnung) geleitet, um die Seite zu verbessern. Diese HOCs sind;
Mit einer Auswahl von Seitentypen, die mit optimizelyProvider durchgeführt werden, ermöglicht dies die Verwendung von Optimizely in den ausgewählten Seitentypen.
Die Variante -HOC stellt sicher, dass Dienste mit Varianten (z. B. simp , lat ) immer zu einer URL weitergeleitet werden, die die entsprechende Variante rendert.
Wenn ein Benutzer zu einer URL navigiert, ohne die Variante bereitzustellen und die Variante in Cookie festgelegt ist, wird die Cookie -Variante -Seite gerendert. Andernfalls wird die Standard -Variante -Seite gerendert
Wenn ein Benutzer mit einer Variante zu einer URL navigiert und eine Variante in Cookie festgelegt ist, wird die Cookie -Variante -Seite gerendert. Andernfalls wird die angeforderte Variante -Seite gerendert.
Die Withcontexts hoc ist ein Wrapper, der Zugriff auf die verschiedenen in der Anwendung verfügbaren Kontextanbieter bietet. Jede untergeordnete Komponente in diesen Kontextanbietern hat Zugriff auf die Kontextdaten über den UseContexts Hook.
Der Page -Wrapper -hoc umhüllt einfach den Artikel oder die Frontpage -Container mit einem Layout. Derzeit haben wir nur ein einzelnes Seitenlayout. Dieses Layout umfasst die Header-, Fußzeilen- und Kontextanbieter, die den Hauptkörper als Kind zwischen dem Kopf und der Fußzeile rendern.
Der Fehler -HOC prüft die übergebene Fehlerquote, wenn der Fehler auf Null des Artikels festgelegt ist oder der Frontpage -Container einfach zurückgegeben wird.
Wenn der Fehler auf true festgelegt wird, wird die Fehlerkomponente zurückgegeben, sodass der Benutzer eine visuelle Anzeige für die Fehlerseite einer 500 -Fehlerseite gibt.
Unter der Annahme, dass die anderen HOCs den ursprünglichen Artikel oder den FrontPage -Container zurückgegeben haben, führt die Daten -HOC einige Validierungsprüfungen für die über die Datenpropie übergebenen JSON -Daten aus. Wenn alle Schecks erfüllt sind, wird der ArticleContainer mit einer einzigen pageData -Requisite zurückgegeben. Diese PageData -Requisiten werden die JSON -Daten beherbergen, die für einen bestimmten Artikel zu den Optimo -Blöcken zurückzuführen sind.
Der HellhashChangeHandler -Hoc ist ein Wrapper, der auf alle Seiten angewendet wird, die nach Änderungen des URL -Hash -Werts prüft. Zu den Seiten gehören Barrierefreiheitskontrollen zum Überspringen von Inhalten, falls der Benutzer dies ausgewählt hat. Dadurch wird der URL -Hash verwendet, um Benutzer in bestimmte Bereiche der Seite zu überspringen. Aufgrund der Art der Client-Seite führt Änderungen an der URL zu einem erneuten Render. Dies führt zu unansehnlichen UI -Flackern für einige Komponenten, insbesondere für Medien und soziale Einbettungen. Dieser HOC wendet Überprüfungen auf die URL an, um zu sehen, ob ein Neurender erforderlich ist, oder wenn Sie einen React.memo nicht erneut verhindern.
Das WithoptimizelyProvider -hoc gibt Komponenten zurück, die mit Zugriff auf einen optimierten Client erweitert wurden, mit dem unsere A/B -Tests durchgeführt werden. Dies geschieht, um die Bündelgrößen zu begrenzen, da wir einige unserer Bündel nach Seitentyp getrennt haben. Wenn wir nur A/B -Tests auf bestimmten Seitentypen durchführen, können wir verhindern, dass die Seitenbündel mit dem Gewicht der SDK -Bibliothek, die wir für optimiert verwenden, verschmutzte Seitenbündel verhindern können.
Mit optimizelyProvider sollte der Wert der handlerBeforeContexts -Objektschlüssel in applaceBasicPageHandlers.js hinzugefügt werden, da der ckns_mvt im UserContext festgelegt wird, sodass der withOptimizelyProvider -hoc neben dem Contexts -hoc in der richtigen Reihenfolge angewendet werden muss. Dies macht das ckns_mvt bei Erstzeitbesuchen zur Verfügung, um den OptimizelyProvider zu übergeben, zusammen mit Attributen wie service , die zur Bestimmung verwendet werden, wann optimis ein Experiment aktiviert werden soll.
Beispiel für Artikelseite:
import withOptimizelyProvider from '#app/legacy/containers/PageHandlers/withOptimizelyProvider' ;
import ArticlePage from './ArticlePage' ;
import applyBasicPageHandlers from '../utils/applyBasicPageHandlers' ;
export default applyBasicPageHandlers ( ArticlePage , {
handlerBeforeContexts : withOptimizelyProvider ,
} ) ;Beim Hinzufügen eines neuen Seitentyps sind mehrere Teile erforderlich.
/data/{{service}}/{{pageType}}/ hinzugefügt werden.json -Suffix verfügbar seinlocalhost:7080/igbo.json sollte die Daten haben, um die Indexseite localhost:7080/igbo zu erstellenmain mit einem flex-grow: 1; Die CSS -Erklärung, dies soll sicherstellen, dass er den Raum zwischen der visuellen Header und der Fußzeile füllt, die Root Div mit einer Flexbox -Implementierung der Sticky -Fußzeile. cypress/support/config/settings.js für jeden Dienst (auch wenn der neue Seitentyp auf undefinierte festgelegt wird)cypress/integration/pages/cypress/integration/pages/ Sie müssen sicherstellenNB: Bei diesen vielen Schritten wird empfohlen, mehrere PRs zu haben, wenn Sie einen neuen Seitentyp hinzufügen, um keine einzigartige große PR zu haben. Wenn jedoch Zypressenstests (Nr. 6) im selben PR nicht wie das Seitenrouting (Nr. 5) hinzugefügt werden, sollten sie sofort der Seitenrouting -PR folgen. Idealerweise sollten diese in einer einzelnen PR behandelt werden.
Bitte lesen Sie: beitragen.md
Knoten installieren. https://nodejs.org/en/. Wir verwenden die in .nvmrc angegebene Version. Wenn Sie einen Node Version Manager (NVM) haben, können Sie das folgende Skript ausführen, um automatisch in die von Projekts unterstützte Version zu wechseln.
nvm use
Das Simorgh -Projekt verwendet Garn für das Paketmanagement. Es wird empfohlen, Garn über den NPM -Paket -Manager zu installieren, der bei der Installation von Node.js in Ihrem System mit Node.js geliefert wird. Führen Sie diesen Befehl aus, um Garn zu installieren:
npm install --global yarn
Dann können Sie die folgenden Befehle ausführen, um Simorgh zu installieren
git clone [email protected]:bbc/simorgh.git
cd simorgh
yarn install
Um diese Anwendung lokal auszuführen, mit heißem Reloading, laufen Sie
yarn dev
Die Anwendung startet unter http: // localhost: 7080.
Artikelseiten werden auf Routen des Formats /news/articles/:id zugestellt, wobei die ID die vom Inhaltsverwaltungssystem generierte Asset -ID ist.
FYI: Artikel in der Verwendung von IDs durch die BBC in der URL erläutert
Diese beiden Nachrichtenartikel sind in der Testumgebung unseres CMS sowie vor Ort verfügbar und werden häufig zum Testen verwendet:
Wir bedienen auch AMP -HTML -Seiten an der Route /news/articles/:id.amp https://www.ampproject.org
Dienste mit Varianten können mit dem obigen Format nicht zugegriffen werden, stattdessen muss die Variante in der URL bereitgestellt werden.
World Service -Fronterseiten werden im Format zugestellt /:service , bei dem service eine Weltdienststelle darstellt:
Die World Service -Front -Seiten folgen auch dem Artikelformat für AMP und sind bei /:service.amp verfügbar:
Dienste mit Varianten können mit dem obigen Format nicht zugegriffen werden, stattdessen muss die Variante in der URL bereitgestellt werden.
Themenseiten verwenden interne BBC -APIs, die nicht öffentlich zugänglich sind. Dies kann dazu führen, dass die folgenden Warnungen bei der lokalen Entwicklung erscheinen:
No BFF_PATH set as environment variable, you will not have access to topics
Interne Entwickler, die vor Ort auf Themenseiten arbeiten müssen, sollten sich an das Team wenden, um Zugang zu erhalten.
Empfehlungen auf Story -Seiten verwenden auch interne BBC -Datenlabor -APIs. Es erfordert das Hinzufügen des Schlüssel-/Wertpaars in envConfig/secret.env -Datei, damit sie lokal angezeigt werden.
Interne Entwickler, die vor Ort auf Artikelseiten arbeiten müssen, sollten sich an das Team wenden, um Zugang zu erhalten.
Sie können andere Seitentypen finden, indem Sie unsere Routen und ihre Associates Regexes durchsehen. Wir empfehlen jedoch, mit dem oben genannten zu beginnen und dann den Kern der Anwendung zu betrachten, um die anderen Routen zu verstehen und zu finden.
Wir verwenden Storybook, um Komponenten isoliert von der Simorgh -Anwendung zu entwickeln. Sie können auf diese unter https://bbc.github.io/simorgh/ zugreifen
Um lokales yarn storybook auszuführen, ist es unter http: // localhost: 9001/erhältlich. Einführung in und Dokumentation für Storybook ist hier: https://storybook.js.org/basics/inTroduction/.
Stellen Sie beim lokalen Anzeigen von Videogeschichten sicher, dass Sie eine BBC -Domäne verwenden, wie im Abschnitt Änderungsanforderungsort beschrieben. Das Video funktioniert nicht in der Hosted -Version von Storybook, die aus diesem Grund oben verlinkt ist.
Wir verwenden auch chromatische QA, um Cross-Browser-Tests auf unseren Geschichten durchzuführen.
Bitte beachten Sie auch, dass Sie, wenn Sie die mit unseren Schriftarten gerenderten Komponenten sehen möchten, eine Repaint der Leinwand erzwingen müssen. Dies liegt daran, dass unsere font-display alle die Eigenschaft von optional oder swap in Übereinstimmung mit den jeweiligen Ladestrategien hier haben: https://ws-downloads.files.bbci.co.uk/fonts/index.html. Der einfachste Weg, ein Repaint zu erzwingen, besteht darin, den Teiler zwischen dem Vorschau -Fenster im Abschnitt und Knobs zu bewegen oder das Browserfenster zu ändern.
Wenn Sie die Anwendung so hosten möchten, dass sie über Ihr lokales Netzwerk zugegriffen werden, befolgen Sie die Anweisungen hier.
Um diese Anwendung lokal mit einem Produktionsbau auszuführen, leiten Sie: yarn build && yarn start .
Wir verwenden yarn build lokal, das die Anwendung auf Localhost für Daten und statische Vermögenswerte aufweist.
Dies wird hauptsächlich zum Debuggen latest mit den Test- und Live -Umgebungsbündeln verwendet. Stellen Sie sicher, dass die Bündel im statischen Asset -Ort für die richtige Umgebung vorhanden sind, bevor Sie mit dem Debuggen beginnen.
Testbündel auf Localhost ausführen:
envConfig/test.env ändern die Werte von:LOG_DIR='/var/log/simorgh' to LOG_DIR='log'rm -rf build && yarn build:test && yarn startLive -Bundles auf Localhost zu laufen:
envConfig/live.env ändern die Werte von:LOG_DIR='/var/log/simorgh' to LOG_DIR='log'rm -rf build && yarn build:live && yarn startEinige Funktionen sind unterschiedlich abhängig davon, ob sich ein Benutzer in Großbritannien oder international befindet. Sie können eine bestimmte Version ausdrücklich anfordern, indem Sie über eine bestimmte lokale BBC -Domäne auf Simorgh zugreifen:
Wenn diese URLs nicht funktionieren, müssen Sie möglicherweise einen Hosts -Dateieintrag hinzufügen ( /etc/hosts oder C:WindowsSystem32driversetchosts ):
127.0.0.1 localhost.bbc.co.uk
127.0.0.1 localhost.bbc.com
Beim Einsatz wird make buildCi in der CI -Umgebung ausgeführt, in der sowohl für die test als auch für die live -Umgebung Bündel erstellt werden. In den beiden Umgebungen überschreiben die .env.test oder .env.live -Dateien die .env -Datei, mit der die Anwendung mit den richtigen Bündeln ausgeführt wird.
Jeder Run of yarn build aktualisiert die Bündelanalysedateien im Repo. Öffnen Sie den generierten HTML-Bericht in einem Browser webpack-bundle-analyzer einem Browser ./reports/webpackBundleReport.html Die Daten sind auch als JSON ./reports/webpackBundleReport.json verfügbar.
Wir haben eine Linie mit dem Airbnb StyleGuide und verwenden hübscher als Codeformatierer. Sie können mit yarn test:lint .
Wir haben Scherz -Unit -Tests, die mit yarn test:unit .
yarn test läuft beide Sätze davon.
Wir verwenden Cypress für unsere End-to-End-Tests. Führen Sie diesen einzelnen Befehl aus, um die Rauchtests lokal durchzuführen:
yarn test:e2e
Es wird einen Produktionsserver auf Port 7080 aufnehmen und die Cypress -Tests dagegen ausführen. Um die Rauchtests interaktiv durchzuführen, laufen Sie:
yarn test:e2e:interactive
Dadurch wird eine Benutzeroberfläche geladen, mit der einzelne Tests neben einem visuellen Stream des Browsers bei der Ausführung der Tests leicht ausgeführt werden können.
Es gibt mehrere Umgebungsvariablen, die Sie mit unserer Testsuite verwenden können, nämlich:
| Umgebungsvariable | Wirkung | Mögliche Werte |
|---|---|---|
| Cypress_only_Service | Beschränkt sich darauf, nur den angegebenen Dienst auszuführen | Ein einzelner Dienst dh CYPRESS_ONLY_SERVICE=urdu |
| Cypress_app_env | Führt die Tests in einer bestimmten Umgebung aus | test , local , live |
| Cypress_Smoke | Läuft nur Rauchtests, wenn wahr | true , false |
| Cypress_uk | Siehe Running E2ES in Großbritannien gegen Live | true , false |
| Cypress_skip_eu | Siehe Laufen E2ES außerhalb der EU | true , false |
Diese Befehle können in Kombination ausgeführt werden.
Die Standardmethode zum Ausführen des E2E -Suite -AKA yarn test:e2e oder yarn test:e2e:interactive führt eine Teilmenge unserer Tests aus, die ansonsten als Rauchtests bekannt sind. Um die volle Suite zu führen:
CYPRESS_SMOKE=false yarn test:e2e
Tests können nur für einen einzelnen Dienst ausgeführt werden, indem sie die Umgebungsvariable CYPRESS_ONLY_SERVICE angeben. Zum Beispiel:
CYPRESS_ONLY_SERVICE=urdu yarn test:e2e
Um nur eine bestimmte Spezifikation auszuführen, muss Cypress direkt aufgerufen werden. Stellen Sie zunächst sicher, dass Simorgh bereits in einer anderen Registerkarte ausgeführt wird, und dann ausführen (z. B. nur Artikel -Tests ausführen):
npx cypress run --spec cypress/integration/pages/articles/index.js
Weitere Details zur Verwendung der Cypress CLI finden Sie unter https://docs.cypress.io/guides/guides/command-line.html
Dies betrifft die Entwickler nur in Großbritannien (kann Sie möglicherweise beeinflussen, wenn Sie ein VPN -Routing durch Großbritannien verwenden).
Die Funktion von Cypress .vissit () ist auf den Besuch einer einzelnen Domäne pro Test gesperrt. Dies wird zu problematisch, wenn Sie die E2E -Tests aus Großbritannien aus dem britischen Start starten, aufgrund von Umleitungen von .com nach .co.uk . Standardmäßig werden Cypress -Tests so ausgeführt, als ob sie außerhalb Großbritanniens durchgeführt wurden. Um diese Tests aus Großbritannien durchzuführen, müssen Sie in der UK Zypressenvariablen für die Tests bestehen. Dies ersetzt die URL -Endungen für .co.uk , mit denen Sie diese Tests erfolgreich durchführen können.
Hier ist ein Beispielbefehl:
CYPRESS_APP_ENV=test CYPRESS_UK=true CYPRESS_SMOKE=true yarn cypress
Dies betrifft Entwickler aus der EU aus (kann Sie jedoch beeinflussen, wenn Sie ein VPN -Routing durch ein Land verwenden, das nicht in der EU ist).
Durch das Ausführen von Zypressen -Tests außerhalb der EU werden die EU -Zustimmungsbanner auf AMP nicht angezeigt, und dies kann dazu führen, dass einige Tests fehlschlagen. Setzen Sie CYPRESS_SKIP_EU=true um zu verhindern, dass diese Tests außerhalb der EU ausgeführt werden.
Ein Beispielbefehl ist:
CYPRESS_SKIP_EU=true yarn cypress:interactive
Der folgende Befehl führt sowohl Simorgh als auch Cypress aus:
CYPRESS_APP_ENV=local CYPRESS_UK=true CYPRESS_SMOKE=true yarn test:e2e
Cypress_app_env kann auch gleich "test" und "live" festgelegt werden. Cypress_Smoke kann wahr oder falsch sein. Es gilt standardmäßig und führt eine bestimmte Teilmenge von Tests aus.
Wir verwenden Leuchtturm, um die Leistung unserer Seite zu testen. Diese wurden jedoch von Simorgh auf unsere eigenen internen CD -Prozesse gebracht. Auf diese Weise können wir diese Tests auf einer genaueren Darstellung von Simorgh durchführen. Sie können den Leuchtturm aus Ihrem Chrom -Browser selbst ausführen oder die Leuchtturm -CLI der Knoten verwenden.
Simorgh nach dem persischen mythologischen Vogel. Der Simorgh ist das Amalgam vieler Vögel (und in einigen Berichten anderen Tieren) in eine.
Glücklicherweise ist eine Metapher, die für das Anbieten aller BBC -Artikel in einer Lösung geeignet zu sein schien, vielleicht noch angemessener, da sich die Anwendung weiterentwickelt, um mehr Inhaltstypen zu unterstützen. Es ist auch ein klarer Hinweis auf die internationale Natur unserer Teams, aber auch auf den Wunsch, Artikel zu gewährleisten (und alles, was gefolgt ist) für Benutzer in allen Sprachen, die die BBC unterstützt.
Es ist auch ein einzigartiger Name, der praktisch ist, und der Vogel ist sehr hübsch.
