diff --git a/developer_manual/basics/front-end/js.rst b/developer_manual/basics/front-end/js.rst index 491b28d6fdb..60206646c13 100644 --- a/developer_manual/basics/front-end/js.rst +++ b/developer_manual/basics/front-end/js.rst @@ -170,11 +170,12 @@ and a JS part (that fetches and parses the state). Providing the initial state with PHP ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Providing state in PHP is done via the ``OCP\AppFramework\Services\IInitialState``. This service -has two methods you can use to provide the initial state. +has two methods you can use to provide the initial state. They will automatically be scoped +to your app, so you don't have to provide your app id anymore. -* ``provideInitialState(string $appName, string $key, $data)``: +* ``provideInitialState(string $key, $data)``: If you know for sure your state will be used. For example on the settings page of your app. -* ``provideLazyInitialState(string $appName, string $key, Closure $closure)``: +* ``provideLazyInitialState(string $key, Closure $closure)``: If you want to inject your state on a general page. For example the initial state of the notifications app. The callback will be invoked if and only if a template is rendered. You call both methods with the name of your app and a key. This is to scope diff --git a/developer_manual/digging_deeper/config/appconfig.rst b/developer_manual/digging_deeper/config/appconfig.rst index e90e60568de..c32c576703c 100644 --- a/developer_manual/digging_deeper/config/appconfig.rst +++ b/developer_manual/digging_deeper/config/appconfig.rst @@ -6,6 +6,29 @@ AppConfig Since v29, Nextcloud includes a new API to manage your app configuration. +AppFramework +------------ + +The AppConfig API is also available in the AppFramework, allowing you to use it in your app. +All of the methods are available in the ``OCP\AppFramework\Services\IAppConfig`` interface. +Any of the methods below will automatically be scoped to your app, meaning you can omit the app id. + +.. code-block:: php + + appConfig->getAppValueString('mykey', 'default'); + } + } Concept overview ---------------- @@ -22,8 +45,8 @@ To ensure better stability of your code, config values are typed enforced. Type is set only once, at creation in database, and cannot be changed. .. note:: - - Value stored before Nextcloud 29 are automatically typed as `mixed`. However, it is not possible to manually set a value as `mixed`. - - Value not set as `mixed` must be retrieved using the corresponding method. + - Value stored before Nextcloud 29 are automatically typed as `mixed`. However, it is not possible to manually set a value as `mixed`. + - Value not set as `mixed` must be retrieved using the corresponding method. Values Sensitivity ^^^^^^^^^^^^^^^^^^ @@ -33,15 +56,15 @@ Configuration values set as `sensitive` are hidden from system reports and store .. code-block:: php - setValueString( - 'myapp', - 'mykey', - 'myvalue', - sensitive: true - ); + setValueString( + 'myapp', + 'mykey', + 'myvalue', + sensitive: true + ); .. note:: - Once set as `sensitive`, it can only be reverted using ``updateSensitive()`` + Once set as `sensitive`, it can only be reverted using ``updateSensitive()`` Lazy Loading @@ -52,33 +75,33 @@ All `lazy` configuration values are loaded from the database once one is read. .. code-block:: php - setValueString( - 'myapp', - 'mykey', - 'myvalue', - lazy: true - ); + setValueString( + 'myapp', + 'mykey', + 'myvalue', + lazy: true + ); .. note:: - - Flag as `lazy` as much 'large block of text' entries (json, key pairs, ...) as possible, - - flag as `lazy` entries that are needed on quiet endpoints, - - do **not** flag as `lazy` part of code that might be called during the global loading of the instance and its apps. + - Flag as `lazy` as much 'large block of text' entries (json, key pairs, ...) as possible, + - flag as `lazy` entries that are needed on quiet endpoints, + - do **not** flag as `lazy` part of code that might be called during the global loading of the instance and its apps. Retrieving the configuration value will require to specify the fact that it is stored as `lazy`. .. code-block:: php - getValueString( - 'myapp', - 'mykey', - 'default', - lazy: true - ); + getValueString( + 'myapp', + 'mykey', + 'default', + lazy: true + ); .. note:: - - Requesting with ``1azy: false`` will returns the default value if configuration value is stored as `lazy`. - - Requesting with ``lazy: true`` will returns the correct value even if configuration value is stored as `non-lazy (as there is a huge probability that the `non-lazy` value are already loaded) + - Requesting with ``1azy: false`` will returns the default value if configuration value is stored as `lazy`. + - Requesting with ``lazy: true`` will returns the correct value even if configuration value is stored as `non-lazy (as there is a huge probability that the `non-lazy` value are already loaded) Consuming the AppConfig API --------------------------- @@ -134,7 +157,7 @@ Managing config keys * ``deleteApp(string $app)`` delete all config keys from an app (using app id) .. note:: - Some method allows ``$lazy`` to be ``null``, meaning that the search will be extended to all configuration values, `lazy` or not. + Some method allows ``$lazy`` to be ``null``, meaning that the search will be extended to all configuration values, `lazy` or not. Miscellaneous ^^^^^^^^^^^^^