m (Rebranding: FANDOM → Fandom) |
m (Make documentation useful again) |
||
Line 1: | Line 1: | ||
+ | {{tocright}} |
||
− | This is the name of the new Fandom application framework. |
||
+ | '''Nirvana''' is the name of Fandom's application framework. In the most basic sense, it consists of controllers and templates these controllers are rendering. Some controllers and their public methods can be accessed through <code>/wikia.php</code> or <code>/api/v1</code> on every Fandom wiki, as well as using the <code>$.nirvana</code> object |
||
− | == |
+ | == Endpoints == |
+ | === <code>/wikia.php</code> === |
||
− | The Quick Start Guide has a summary of example usage for the most common functions in the framework. |
||
+ | Script for accessing methods of any class extending <code>WikiaController</code> that allows external requests. Accepts two arguments as query string parameters: |
||
− | * [[Nirvana/Quick Start Guide|Quick Start Guide]] |
||
+ | * <code>controller</code> — Controller to access. If the class name of the controller is <code>SomethingController</code>, this field accepts both <code>Something</code> and <code>SomethingController</code> in order to access it. |
||
− | * [[Nirvana/JavaScript|JavaScript helper functions]] |
||
+ | * <code>method</code> — Public method to access. Defaults to <code>index</code>. Case-insensitive due to PHP method name case-insensitivity. |
||
+ | * <code>format</code> — Can be set to [[wikipedia:JSON|<code>json</code>]] or [[wikipedia:HTML|<code>html</code>]]. Default is <code>html</code>, but methods with no templates associated just return data as JSON. |
||
+ | For example, [{{SERVER}}/wikia.php?controller=UserProfilePage&method=renderUserIdentityBox&title=User:KockaAdmiralac&format=json <code>/wikia.php?controller=UserProfilePage&method=renderUserIdentityBox&title=User:KockaAdmiralac&format=json</code>] calls the [[github:Wikia/app/blob/dev/extensions/wikia/UserProfilePageV3/UserProfilePageController.class.php#L49-L110|<code>renderUserIdentityBox</code> method of the <code>UserProfilePageController</code> class]] and requests that the data is returned as JSON. |
||
+ | === <code>/api/v1</code> === |
||
− | == Nirvana Framework reference == |
||
+ | Can access only a subset of externally accessible controllers. Accessible controllers are those whose names end with <code>ApiController</code> with public method names starting with <code>get</code>. Always returns data as JSON. For example, [{{SERVER}}/api/v1/User/Details?ids=KockaAdmiralac <code>/api/v1/Users/Details?ids=KockaAdmiralac</code>] accesses the [[github:Wikia/app/blob/dev/includes/wikia/api/UserApiController.class.php#L24-L75|<code>getDetails</code> method of the <code>UserApiController</code> class]]. |
||
− | This section documents each object in the framework. |
||
− | * [[Nirvana/WikiaApp|WikiaApp]] |
||
− | * [[Nirvana/WikiaController|WikiaController]] |
||
− | * [[Nirvana/WikiaService|WikiaService]] |
||
− | * [[Nirvana/WikiaObject|WikiaObject]] |
||
− | * [[Nirvana/WikiaModel|WikiaModel]] |
||
− | * [[Nirvana/WikiaSpecialPageController|WikiaSpecialPageController]] |
||
− | * [[Nirvana/WikiaRequest|WikiaRequest]] |
||
− | * [[Nirvana/WikiaResponse|WikiaResponse]] |
||
− | * [[Nirvana/WikiaException|WikiaException]] |
||
− | * [[Nirvana/WikiaView|WikiaView]] |
||
+ | Controllers accessible through <code>/api/v1</code> often have their parameters and responses documented [{{SERVER}}/api/v1 on the same page]. Some controllers, such as the [[github:Wikia/app/blob/dev/includes/wikia/api/WikisApiController.class.php|<code>WikisApiController</code>]] are only accessible from [[w:|Community Central]]. |
||
− | The following classes are internal and should not be used directly |
||
− | * [[Nirvana/WikiaRegistry|WikiaRegistry]] |
||
− | * [[Nirvana/WikiaDispatcher|WikiaDispatcher]] |
||
+ | == JavaScript == |
||
− | Articles that contain performance information, structure, documentation, etc for Nirvana should be in Category:Nirvana, which will be picked up below. |
||
+ | There is a helper object for accessing Nirvana's endpoints from client-side scripts defined in [[github:Wikia/app/blob/dev/resources/wikia/modules/nirvana.js|<code>wikia.nirvana</code> AMD module]]: <code>$.nirvana</code>. |
||
+ | |||
+ | === Methods === |
||
+ | ; <code>$.nirvana.sendRequest(attr)</code> |
||
+ | : Used for sending requests to <code>/wikia.php</code>, given the controller, method name and data. |
||
+ | : <code>attr</code> is an object consisting of the following: |
||
+ | :* <code>controller</code> — Controller name. '''Required parameter.''' |
||
+ | :* <code>method</code> — Method name. '''Required parameter.''' |
||
+ | :* <code>format</code> — Format of the response. Can be set to <code>json</code> (default), <code>html</code> or <code>jsonp</code>. |
||
+ | :* <code>type</code> — Can be set to <code>GET</code> or <code>POST</code> (default). |
||
+ | :* <code>data</code> — Object with parameters to pass to the controller. If set to a string, converts it to the format of the response. |
||
+ | :* <code>callback</code> — Function called after the request succeeds. |
||
+ | :* <code>onErrorCallback</code> — Function called after the request fails. |
||
+ | :* <code>contentType</code> — Passed as a <code>contentType</code> parameter in an <code>$.ajax()</code> call. |
||
+ | :* <code>processData</code> — Passed as a <code>processData</code> parameter in an <code>$.ajax()</code> call. |
||
+ | :* <code>scriptPath</code> — Used instead of the <code>wgScriptPath</code> variable. |
||
+ | ; <code>$nirvana.getUrl(options)</code> |
||
+ | : Used for obtaining a <code>/wikia.php</code> URL. |
||
+ | : <code>options</code> is an object consisting of the following: |
||
+ | :* <code>controller</code> — Controller name. '''Required parameter.''' |
||
+ | :* <code>method</code> — Method name. '''Required parameter.''' |
||
+ | :* <code>format</code> — Format of the response. Can be set to <code>json</code> (default), <code>html</code> or <code>jsonp</code>. |
||
+ | :* <code>scriptPath</code> — Used instead of the <code>wgScriptPath</code> variable. |
||
+ | :* <code>data</code> — Object with parameters to pass to the controller. If set to a string, converts it to the format of the response. |
||
+ | ; <code>$nirvana.getJson(controller, method, data, callback, onErrorCallback)</code> |
||
+ | : Shorthand for sending a GET request to Nirvana. |
||
+ | : Parameters are as described in the <code>sendRequest</code> method. <code>method</code> parameter may be omitted. |
||
+ | ; <code>$nirvana.postJson(controller, method, data, callback, onErrorCallback)</code> |
||
+ | : Shorthand for sending a POST request to Nirvana. |
||
+ | : Parameters are as described in the <code>sendRequest</code> method. <code>method</code> parameter may be omitted. |
||
+ | |||
+ | == Available controllers == |
||
+ | There are many Nirvana controllers available, but only a few of them are properly documented. The easiest way to find them is to [[github:Wikia/app/find/dev|use the file search option in Fandom's MediaWiki code repository]] and search for <code>Controller.class.php</code>. If you are unsure about how a controller can be used, feel free to leave a message on {{SITENAME}}'s [[Board:API Discussion|API Discussion board]], and other users who worked with Nirvana controllers in past may be able to help you. |
||
+ | |||
+ | == Definitions == |
||
+ | These classes are used within the Nirvana framework. |
||
+ | ; <code>WikiaApp</code> |
||
+ | : Wrapper for many common operations, such as hooks registration and getting access to global variables. |
||
+ | ; <code>WikiaController</code> |
||
+ | : Wraps queries and data related logic into functions for the front end. |
||
+ | : Can be accessed through <code>/wikia.php</code> or <code>/api/v1</code> endpoints. |
||
+ | ; <code>WikiaException</code> |
||
+ | : The exception class typically thrown by Nirvana controllers. |
||
+ | ; <code>WikiaModel</code> |
||
+ | : Abstract class for other helper classes with methods for database access. |
||
+ | ; <code>WikiaObject</code> |
||
+ | : Abstract class extended by non-controllers that still need framework variables. |
||
+ | ; <code>WikiaRequest</code> |
||
+ | : An incomplete replacement for MediaWiki's <code>[[mw:Manual:WebRequest.php|WebRequest]]</code> class. |
||
+ | ; <code>WikiaResponse</code> |
||
+ | : Used for passing data between controllers and templates. |
||
+ | : Any variables set in the response are in the JSON response of the controller. |
||
+ | ; <code>WikiaService</code> |
||
+ | : Class for controllers that cannot be accessed externally. |
||
+ | ; <code>WikiaSpecialPageController</code> |
||
+ | : Class for controllers used for controlling [[Special:SpecialPages|special page]] features. |
||
+ | ; <code>WikiaView</code> |
||
+ | : Class representing a template. |
||
== See also == |
== See also == |
||
− | * [[github:Wikia/app/tree/dev/includes/wikia/nirvana|Nirvana in |
+ | * [[github:Wikia/app/tree/dev/includes/wikia/nirvana|Nirvana in Fandom's MediaWiki code repository]]. |
+ | |||
− | [[Category: |
+ | [[Category:Guides]] |
Revision as of 23:15, 2 February 2019
Nirvana is the name of Fandom's application framework. In the most basic sense, it consists of controllers and templates these controllers are rendering. Some controllers and their public methods can be accessed through /wikia.php
or /api/v1
on every Fandom wiki, as well as using the $.nirvana
object
Endpoints
/wikia.php
Script for accessing methods of any class extending WikiaController
that allows external requests. Accepts two arguments as query string parameters:
controller
— Controller to access. If the class name of the controller isSomethingController
, this field accepts bothSomething
andSomethingController
in order to access it.method
— Public method to access. Defaults toindex
. Case-insensitive due to PHP method name case-insensitivity.format
— Can be set tojson
orhtml
. Default ishtml
, but methods with no templates associated just return data as JSON.
For example, /wikia.php?controller=UserProfilePage&method=renderUserIdentityBox&title=User:KockaAdmiralac&format=json
calls the renderUserIdentityBox
method of the UserProfilePageController
class and requests that the data is returned as JSON.
/api/v1
Can access only a subset of externally accessible controllers. Accessible controllers are those whose names end with ApiController
with public method names starting with get
. Always returns data as JSON. For example, /api/v1/Users/Details?ids=KockaAdmiralac
accesses the getDetails
method of the UserApiController
class.
Controllers accessible through /api/v1
often have their parameters and responses documented on the same page. Some controllers, such as the WikisApiController
are only accessible from Community Central.
JavaScript
There is a helper object for accessing Nirvana's endpoints from client-side scripts defined in wikia.nirvana
AMD module: $.nirvana
.
Methods
$.nirvana.sendRequest(attr)
- Used for sending requests to
/wikia.php
, given the controller, method name and data. attr
is an object consisting of the following:controller
— Controller name. Required parameter.method
— Method name. Required parameter.format
— Format of the response. Can be set tojson
(default),html
orjsonp
.type
— Can be set toGET
orPOST
(default).data
— Object with parameters to pass to the controller. If set to a string, converts it to the format of the response.callback
— Function called after the request succeeds.onErrorCallback
— Function called after the request fails.contentType
— Passed as acontentType
parameter in an$.ajax()
call.processData
— Passed as aprocessData
parameter in an$.ajax()
call.scriptPath
— Used instead of thewgScriptPath
variable.
$nirvana.getUrl(options)
- Used for obtaining a
/wikia.php
URL. options
is an object consisting of the following:controller
— Controller name. Required parameter.method
— Method name. Required parameter.format
— Format of the response. Can be set tojson
(default),html
orjsonp
.scriptPath
— Used instead of thewgScriptPath
variable.data
— Object with parameters to pass to the controller. If set to a string, converts it to the format of the response.
$nirvana.getJson(controller, method, data, callback, onErrorCallback)
- Shorthand for sending a GET request to Nirvana.
- Parameters are as described in the
sendRequest
method.method
parameter may be omitted. $nirvana.postJson(controller, method, data, callback, onErrorCallback)
- Shorthand for sending a POST request to Nirvana.
- Parameters are as described in the
sendRequest
method.method
parameter may be omitted.
Available controllers
There are many Nirvana controllers available, but only a few of them are properly documented. The easiest way to find them is to use the file search option in Fandom's MediaWiki code repository and search for Controller.class.php
. If you are unsure about how a controller can be used, feel free to leave a message on Fandom Developers Wiki's API Discussion board, and other users who worked with Nirvana controllers in past may be able to help you.
Definitions
These classes are used within the Nirvana framework.
WikiaApp
- Wrapper for many common operations, such as hooks registration and getting access to global variables.
WikiaController
- Wraps queries and data related logic into functions for the front end.
- Can be accessed through
/wikia.php
or/api/v1
endpoints. WikiaException
- The exception class typically thrown by Nirvana controllers.
WikiaModel
- Abstract class for other helper classes with methods for database access.
WikiaObject
- Abstract class extended by non-controllers that still need framework variables.
WikiaRequest
- An incomplete replacement for MediaWiki's
WebRequest
class. WikiaResponse
- Used for passing data between controllers and templates.
- Any variables set in the response are in the JSON response of the controller.
WikiaService
- Class for controllers that cannot be accessed externally.
WikiaSpecialPageController
- Class for controllers used for controlling special page features.
WikiaView
- Class representing a template.