Overview of the Oppia codebase（Oppia程式碼程式庫總覽）

標籤：

Oppia is built with Google App Engine. Its backend is written in Python, and its frontend is written using AngularJS.

Oppia是基於Google App Engine開發建設的。它的後台是用Python編寫，前端是用AngularJS編寫。

The core核心

 

Most of Oppia‘s functionality is in the core/ directory, which is arranged as follows:

 大部分的Oppia功能都放置在core目錄中，範圍如下所示

Backend 後台

One way to understand what this diagram means is to look at the lifecycle of a typical request. A user makes a request to the Oppia server by performing some action (like clicking a button) that causes some JavaScript code to issue a POST request. This request is made to a particular URL, which main.py matches to a handler in the core/controllers directory.

理解這張圖的含義的一種方式是透過一個典型請求的生命週期。一個使用者發出一個請求到Oppia伺服器通過執行一些動作（像點擊了一個按鈕），這引起了某些JavaScript代碼處理一個POST請求。這個請求指向一個特定的URL，main.py匹配處理器在core/controllers目錄中。

Each controller is meant to be a thin layer that understands and validates the request, and then calls methods in core/domain to actually perform the computation/query, or change the state of the data on the server. The files in core/domain constitute the core functionality of Oppia and are where most of the logical operations occur.

每個控制器意味著是一個薄層，用於理解和確認請求，然後調用在core/domain的方法來實際地執行計算或查詢，在伺服器上更改資料的狀態。在core/domain目錄的檔案組成了Oppia的核心功能，也是邏輯操作發生的地方。

In core/domain, there are generally two types of files: those whose names end in _domain.py, and those whose names end in _services.py. Files of the form *_services.py are mostly comprised of functions that act on data. On the other hand, files of the form *_domain.py define transient classes that represent Oppia objects (like explorations, states/cards, and so on); these classes are generally initialized using data from persistent storage, and are then operated on by functions in the *_services.py files.

在core/domain目錄，通常有兩種類型的檔案：一種是以_domain.py結尾的檔案，一種是以_services.py結尾的檔案。以_services.py結尾的檔案絕大多數包含操作資料的功能。另一方面，以_domain.py結尾的檔案定義了代表Oppia對象的臨時類（像探索，狀態/卡片，等等），這些類通常使用從永久儲存獲得的資料進行初始化，然後被*_services.py檔案中的功能操作。

Methods in the domain layer often need to access storage, memcache and other services provided by the application framework. All framework-dependent code (such as anything with a dependency on ndb or google.appengine) should go in core/platform. The platforms/models.py class provides an interface to these services, and refers to the correct classes based on what the underlying framework is at runtime. All files in the templates, controllers and domain layers should be independent of the underlying framework.

在domain層的方法經常需要訪問儲存，記憶體和其他的應用程式架構提供的服務。所有架構依賴的代碼（如任何依賴於ndb或者GAE）應該放置在core/platform目錄中。platforms/models.py類提供了一個介面這些服務，引用到正確的類基於架構在運行時。所有的檔案在templates、controllers和domain層應基於架構依賴。

The backend codebase is heavily tested. Tests are contained in *_test.py files next to the Python module they test. This naming convention allows them to be automatically detected and compiled into a test suite by Python‘s unittest module. For more information, see Running Tests.

後台程式碼程式庫是被嚴肅測試過的。測試包含在*_test.py檔案指向到python模組。這種命名習慣要求他們被自動檢測和編譯，在Python的unittest模組測試套件。獲得更多的資訊，請看Running Tests.

Frontend 前端

The developer version of the frontend code is contained in core/templates/dev/head. (When Oppia is deployed, a core/templates/prod/head directory is also produced that contains minified versions of the code, but this is not generally of concern during development.) The frontend code contains the following sub-directories:。

前端代碼的開發人員版本包含在core/templates/dev/head檔案夾中（當Oppia被部署時，core/templates/prod/head/目錄被產生，包含了代碼的縮小版，但是這在開發期間一般是不關心的）前端的程式碼封裝含在下面的子目錄中：

• admin: This provides the /admin page which exposes admin controls, e.g. for adding new moderators. admin目錄：它提供/admin頁，暴露admin控制，如添加新夥伴。
• components: This provides certain components, mostly for the editor. In particular there arerule_editor.html for the rule editor and visualizations.html for the state graph.components：它提供了一定的組件，主要是編輯器。特殊情況下，有rule_editor.html對rule editor，visualizations.html 對狀態圖。
• css: Site-wide CSS. There may be other CSS blocks within individual HTML files.css：網站範圍的CSS.可能有其他的CSS塊在各自的HTML檔案。
• dashboard: The per-user notifications dashboard.dashboard：每個使用者通知儀錶盤。
• editor: The editor; this constitutes by far the largest and most complex section of code.editor：編輯器，這個有最大的和最複雜的代碼部分。
• error: Pages to display when a page cannot be loaded (e.g. due to unauthorised access).error：頁面顯示當一個頁面不能被載入（比如沒有許可權訪問）。
• expressions: Code to parse and evaluate expressions (which may use parameters).expressions：代碼解析和評估運算式（可使用參數）
• forms: Certain standard objects are used in various places throughout the website, such as rich text, lists and dictionaries. Code used to display editors for these objects is collected here.forms：表單，確定的標準對象唄用在很多地方在整個網站，如，富文本，列表，字典。用來顯示編輯器的代碼收集在這裡。
• galleries: The gallery page that allows users to browse explorations.galleries：分類頁允許使用者瀏覽探索。
• moderator: The /moderator page that provides functionality for moderators.moderator：版首頁提供了對版主的功能。
• pages: Various static pages, such as the site guidelines.pages：大量的靜態頁，比如網站指南
• player: Services for the learner view. (The actual learner view templates are inextensions/skins.)player：學習者視圖服務（實際的學習者模板在extensiongs/skins）
• profile: Used when a new user registers, and to display usernames for logged-in users.profile：當一個新使用者註冊是使用，顯示登入的使用者名稱。
• services: JavaScript handling the embedding of explorations in other websites, user warnings and other matters.services：JavaScript處理封裝的探索在其他的網站，使用者警告和其他內容。

Files generally come in triples of the form state_editor.html, StateEditor.js andStateEditorSpec.js. The spec file contains Karma unit tests for the JavaScript file.

檔案一般以元組形式出現：state_editor.html，StateEditor.js 和StateEditorSpec.js。這個spec檔案包含karma unit test 的javascript檔案。

In general, within the HTML file, sections of the DOM are bound to particular JavaScript controllers. However, some JavaScript files cover multiple HTML files, and others provide general services and so have no HTML file.

通常，在html檔案中，DOM的部分綁定到特定的JavaScript控制器。但是，一些JavaScript檔案覆蓋了多個html檔案，還有其他的提供了一般的服務，因此，沒有html檔案。

Extensions擴充

Oppia has a number of extension points that allow developers to augment its functionality, all of which are located in the extensions/ folder.

Oppia擁有大量的擴充點，允許開發人員增強它的功能，所有的這些被放置在extensions/目錄。

There are several different types of extensions:

幾種不同類型的擴充：

• Objects represent object types that Oppia recognizes, such as NonnegativeInt, UnicodeString and Filepath. In general, they each come with an editor view, a readonly view, and a normalizer which tries to convert a Python object to the given type.Objects代表了Oppia識別的物件類型，比如非負整數、Unicode字串、檔案路徑。通常，它們每一個跟著一個編輯器視圖，一個唯讀視圖，和一個轉化器轉換Python對象到一個給定的類型。
• Rules allow learner answers to be classified, so that Oppia can provide appropriate feedback in response.Rules規則，要求學習者的回答被分類，以便Oppia能提供近似的反饋作為回應。
• Skins provide different user interfaces for the Oppia learner view.Skins提供不同使用者介面對於Oppia學習者視圖。
• Value generators are essentially functions which take some inputs and produce a single output. They are used when defining parameter changes: for example, they allow an exploration author to specify an exact value for the parameter, or a range of values, one of which is selected at random.Value generators值產生器是必須的功能，獲得一些輸入和產生單一的輸出。他們被使用當定義參數變更：例如，他們要求一些探索作者指定一個準確的值對於參數，或者一個值範圍，其中一個被隨機播放。
• Rich-text-editor extensions provide additional functionality for content that is shown to the learner. They are accessed via control buttons in the rich-text editor toolbar, and include things like videos, images, links and LaTeX math expressions.Rich-text-editor extensions富文字編輯器擴充提供了另外的功能對content被顯示給學習者。他們被訪問通過控制按鈕在富文字編輯器中，包含像視頻，映像，連結和LaTeX數學運算式。
• Interactions, such as interactive maps and numeric input, allow the learner to submit an answer, which is then sent to the server for Oppia to respond to.Interactions互動，比如互動的地圖和數字輸入，要求學習者提交一個答案，這些被發送到伺服器獲得Oppia的回饋。

Other files and folders其他的檔案和檔案夾

• feconf.py contains various constants that are referred to by other backend files in the app.feconf.py包含大量的約束被其他後台檔案所引用。
• The data/explorations folder contains sample explorations that are bundled with the Oppia distribution.data/explorations檔案夾包含例子探索綁定到Oppia共用
• The scripts/ folder contains several utility scripts that automate processes like starting a development server, running tests, and deploying a copy of Oppia to a production server.scripts檔案夾包含幾個工具指令碼自動處理像啟動一個程式開發伺服器，運行測試，部署Oppia的一個copy為一個產品。

TODO: in the boxes in the diagram, consider giving a concrete example of a controller, domain model, etc. and walk up and down through the stack, maybe pointing to code examples. (This may be useful for new contributors who are not familiar with the codebase.)

Overview of the Oppia codebase（Oppia程式碼程式庫總覽）